1 /*
2 * This file is produced automatically.
3 * Do not modify anything in here by hand.
4 *
5 * Created from source file
6 * device_if.m
7 * with
8 * makeobjops.awk
9 *
10 * See the source file for legal information
11 */
12
13 /**
14 * @defgroup DEVICE device - KObj methods for all device drivers
15 * @brief A basic set of methods required for all device drivers.
16 *
17 * The device interface is used to match devices to drivers during
18 * autoconfiguration and provides methods to allow drivers to handle
19 * system-wide events such as suspend, resume or shutdown.
20 * @{
21 */
22
23 #ifndef _device_if_h_
24 #define _device_if_h_
25
26 /** @brief Unique descriptor for the DEVICE_PROBE() method */
27 extern struct kobjop_desc device_probe_desc;
28 /** @brief A function implementing the DEVICE_PROBE() method */
29 typedef int device_probe_t(device_t dev);
30 /**
31 * @brief Probe to see if a device matches a driver.
32 *
33 * Users should not call this method directly. Normally, this
34 * is called via device_probe_and_attach() to select a driver
35 * calling the DEVICE_PROBE() of all candidate drivers and attach
36 * the winning driver (if any) to the device.
37 *
38 * This function is used to match devices to device drivers.
39 * Typically, the driver will examine the device to see if
40 * it is suitable for this driver. This might include checking
41 * the values of various device instance variables or reading
42 * hardware registers.
43 *
44 * In some cases, there may be more than one driver available
45 * which can be used for a device (for instance there might
46 * be a generic driver which works for a set of many types of
47 * device and a more specific driver which works for a subset
48 * of devices). Because of this, a driver should not assume
49 * that it will be the driver that attaches to the device even
50 * if it returns a success status from DEVICE_PROBE(). In particular,
51 * a driver must free any resources which it allocated during
52 * the probe before returning. The return value of DEVICE_PROBE()
53 * is used to elect which driver is used - the driver which returns
54 * the largest non-error value wins the election and attaches to
55 * the device. Common non-error values are described in the
56 * DEVICE_PROBE(9) manual page.
57 *
58 * If a driver matches the hardware, it should set the device
59 * description string using device_set_desc() or
60 * device_set_desc_copy(). This string is used to generate an
61 * informative message when DEVICE_ATTACH() is called.
62 *
63 * As a special case, if a driver returns zero, the driver election
64 * is cut short and that driver will attach to the device
65 * immediately. This should rarely be used.
66 *
67 * For example, a probe method for a PCI device driver might look
68 * like this:
69 *
70 * @code
71 * int
72 * foo_probe(device_t dev)
73 * {
74 * if (pci_get_vendor(dev) == FOOVENDOR &&
75 * pci_get_device(dev) == FOODEVICE) {
76 * device_set_desc(dev, "Foo device");
77 * return (BUS_PROBE_DEFAULT);
78 * }
79 * return (ENXIO);
80 * }
81 * @endcode
82 *
83 * To include this method in a device driver, use a line like this
84 * in the driver's method list:
85 *
86 * @code
87 * KOBJMETHOD(device_probe, foo_probe)
88 * @endcode
89 *
90 * @param dev the device to probe
91 *
92 * @retval 0 if this is the only possible driver for this
93 * device
94 * @retval negative if the driver can match this device - the
95 * least negative value is used to select the
96 * driver
97 * @retval ENXIO if the driver does not match the device
98 * @retval positive if some kind of error was detected during
99 * the probe, a regular unix error code should
100 * be returned to indicate the type of error
101 * @see DEVICE_ATTACH(), pci_get_vendor(), pci_get_device()
102 */
103
DEVICE_PROBE(device_t dev)104 static __inline int DEVICE_PROBE(device_t dev)
105 {
106 kobjop_t _m;
107 KOBJOPLOOKUP(((kobj_t)dev)->ops,device_probe);
108 return ((device_probe_t *) _m)(dev);
109 }
110
111 /** @brief Unique descriptor for the DEVICE_IDENTIFY() method */
112 extern struct kobjop_desc device_identify_desc;
113 /** @brief A function implementing the DEVICE_IDENTIFY() method */
114 typedef void device_identify_t(driver_t *driver, device_t parent);
115 /**
116 * @brief Allow a device driver to detect devices not otherwise enumerated.
117 *
118 * The DEVICE_IDENTIFY() method is used by some drivers (e.g. the ISA
119 * bus driver) to help populate the bus device with a useful set of
120 * child devices, normally by calling the BUS_ADD_CHILD() method of
121 * the parent device. For instance, the ISA bus driver uses several
122 * special drivers, including the isahint driver and the pnp driver to
123 * create child devices based on configuration hints and PnP bus
124 * probes respectively.
125 *
126 * Many bus drivers which support true plug-and-play do not need to
127 * use this method at all since child devices can be discovered
128 * automatically without help from child drivers.
129 *
130 * To include this method in a device driver, use a line like this
131 * in the driver's method list:
132 *
133 * @code
134 * KOBJMETHOD(device_identify, foo_identify)
135 * @endcode
136 *
137 * @param driver the driver whose identify method is being called
138 * @param parent the parent device to use when adding new children
139 */
140
DEVICE_IDENTIFY(driver_t * driver,device_t parent)141 static __inline void DEVICE_IDENTIFY(driver_t *driver, device_t parent)
142 {
143 kobjop_t _m;
144 KOBJOPLOOKUP(driver->ops,device_identify);
145 ((device_identify_t *) _m)(driver, parent);
146 }
147
148 /** @brief Unique descriptor for the DEVICE_ATTACH() method */
149 extern struct kobjop_desc device_attach_desc;
150 /** @brief A function implementing the DEVICE_ATTACH() method */
151 typedef int device_attach_t(device_t dev);
152 /**
153 * @brief Attach a device to a device driver
154 *
155 * Normally only called via device_probe_and_attach(), this is called
156 * when a driver has succeeded in probing against a device.
157 * This method should initialise the hardware and allocate other
158 * system resources (e.g. devfs entries) as required.
159 *
160 * To include this method in a device driver, use a line like this
161 * in the driver's method list:
162 *
163 * @code
164 * KOBJMETHOD(device_attach, foo_attach)
165 * @endcode
166 *
167 * @param dev the device to probe
168 *
169 * @retval 0 success
170 * @retval non-zero if some kind of error was detected during
171 * the attach, a regular unix error code should
172 * be returned to indicate the type of error
173 * @see DEVICE_PROBE()
174 */
175
DEVICE_ATTACH(device_t dev)176 static __inline int DEVICE_ATTACH(device_t dev)
177 {
178 kobjop_t _m;
179 KOBJOPLOOKUP(((kobj_t)dev)->ops,device_attach);
180 return ((device_attach_t *) _m)(dev);
181 }
182
183 /** @brief Unique descriptor for the DEVICE_DETACH() method */
184 extern struct kobjop_desc device_detach_desc;
185 /** @brief A function implementing the DEVICE_DETACH() method */
186 typedef int device_detach_t(device_t dev);
187 /**
188 * @brief Detach a driver from a device.
189 *
190 * This can be called if the user is replacing the
191 * driver software or if a device is about to be physically removed
192 * from the system (e.g. for removable hardware such as USB or PCCARD).
193 *
194 * To include this method in a device driver, use a line like this
195 * in the driver's method list:
196 *
197 * @code
198 * KOBJMETHOD(device_detach, foo_detach)
199 * @endcode
200 *
201 * @param dev the device to detach
202 *
203 * @retval 0 success
204 * @retval non-zero the detach could not be performed, e.g. if the
205 * driver does not support detaching.
206 *
207 * @see DEVICE_ATTACH()
208 */
209
DEVICE_DETACH(device_t dev)210 static __inline int DEVICE_DETACH(device_t dev)
211 {
212 kobjop_t _m;
213 KOBJOPLOOKUP(((kobj_t)dev)->ops,device_detach);
214 return ((device_detach_t *) _m)(dev);
215 }
216
217 /** @brief Unique descriptor for the DEVICE_SHUTDOWN() method */
218 extern struct kobjop_desc device_shutdown_desc;
219 /** @brief A function implementing the DEVICE_SHUTDOWN() method */
220 typedef int device_shutdown_t(device_t dev);
221 /**
222 * @brief Called during system shutdown.
223 *
224 * This method allows drivers to detect when the system is being shut down.
225 * Some drivers need to use this to place their hardware in a consistent
226 * state before rebooting the computer.
227 *
228 * To include this method in a device driver, use a line like this
229 * in the driver's method list:
230 *
231 * @code
232 * KOBJMETHOD(device_shutdown, foo_shutdown)
233 * @endcode
234 */
235
DEVICE_SHUTDOWN(device_t dev)236 static __inline int DEVICE_SHUTDOWN(device_t dev)
237 {
238 kobjop_t _m;
239 KOBJOPLOOKUP(((kobj_t)dev)->ops,device_shutdown);
240 return ((device_shutdown_t *) _m)(dev);
241 }
242
243 /** @brief Unique descriptor for the DEVICE_SUSPEND() method */
244 extern struct kobjop_desc device_suspend_desc;
245 /** @brief A function implementing the DEVICE_SUSPEND() method */
246 typedef int device_suspend_t(device_t dev);
247 /**
248 * @brief This is called by the power-management subsystem when a
249 * suspend has been requested by the user or by some automatic
250 * mechanism.
251 *
252 * This gives drivers a chance to veto the suspend or save their
253 * configuration before power is removed.
254 *
255 * To include this method in a device driver, use a line like this in
256 * the driver's method list:
257 *
258 * @code
259 * KOBJMETHOD(device_suspend, foo_suspend)
260 * @endcode
261 *
262 * @param dev the device being suspended
263 *
264 * @retval 0 success
265 * @retval non-zero an error occurred while attempting to prepare the
266 * device for suspension
267 *
268 * @see DEVICE_RESUME()
269 */
270
DEVICE_SUSPEND(device_t dev)271 static __inline int DEVICE_SUSPEND(device_t dev)
272 {
273 kobjop_t _m;
274 KOBJOPLOOKUP(((kobj_t)dev)->ops,device_suspend);
275 return ((device_suspend_t *) _m)(dev);
276 }
277
278 /** @brief Unique descriptor for the DEVICE_RESUME() method */
279 extern struct kobjop_desc device_resume_desc;
280 /** @brief A function implementing the DEVICE_RESUME() method */
281 typedef int device_resume_t(device_t dev);
282 /**
283 * @brief This is called when the system resumes after a suspend.
284 *
285 * To include this method in a device driver, use a line like this
286 * in the driver's method list:
287 *
288 * @code
289 * KOBJMETHOD(device_resume, foo_resume)
290 * @endcode
291 *
292 * @param dev the device being resumed
293 *
294 * @retval 0 success
295 * @retval non-zero an error occurred while attempting to restore the
296 * device from suspension
297 *
298 * @see DEVICE_SUSPEND()
299 */
300
DEVICE_RESUME(device_t dev)301 static __inline int DEVICE_RESUME(device_t dev)
302 {
303 kobjop_t _m;
304 KOBJOPLOOKUP(((kobj_t)dev)->ops,device_resume);
305 return ((device_resume_t *) _m)(dev);
306 }
307
308 /** @brief Unique descriptor for the DEVICE_QUIESCE() method */
309 extern struct kobjop_desc device_quiesce_desc;
310 /** @brief A function implementing the DEVICE_QUIESCE() method */
311 typedef int device_quiesce_t(device_t dev);
312 /**
313 * @brief This is called when the driver is asked to quiesce itself.
314 *
315 * The driver should arrange for the orderly shutdown of this device.
316 * All further access to the device should be curtailed. Soon there
317 * will be a request to detach, but there won't necessarily be one.
318 *
319 * To include this method in a device driver, use a line like this
320 * in the driver's method list:
321 *
322 * @code
323 * KOBJMETHOD(device_quiesce, foo_quiesce)
324 * @endcode
325 *
326 * @param dev the device being quiesced
327 *
328 * @retval 0 success
329 * @retval non-zero an error occurred while attempting to quiesce the
330 * device
331 *
332 * @see DEVICE_DETACH()
333 */
334
DEVICE_QUIESCE(device_t dev)335 static __inline int DEVICE_QUIESCE(device_t dev)
336 {
337 kobjop_t _m;
338 KOBJOPLOOKUP(((kobj_t)dev)->ops,device_quiesce);
339 return ((device_quiesce_t *) _m)(dev);
340 }
341
342 /** @brief Unique descriptor for the DEVICE_REGISTER() method */
343 extern struct kobjop_desc device_register_desc;
344 /** @brief A function implementing the DEVICE_REGISTER() method */
345 typedef void * device_register_t(device_t dev);
346 /**
347 * @brief This is called when the driver is asked to register handlers.
348 *
349 *
350 * To include this method in a device driver, use a line like this
351 * in the driver's method list:
352 *
353 * @code
354 * KOBJMETHOD(device_register, foo_register)
355 * @endcode
356 *
357 * @param dev the device for which handlers are being registered
358 *
359 * @retval NULL method not implemented
360 * @retval non-NULL a pointer to implementation specific static driver state
361 *
362 */
363
DEVICE_REGISTER(device_t dev)364 static __inline void * DEVICE_REGISTER(device_t dev)
365 {
366 kobjop_t _m;
367 KOBJOPLOOKUP(((kobj_t)dev)->ops,device_register);
368 return ((device_register_t *) _m)(dev);
369 }
370
371 #endif /* _device_if_h_ */
372