1 | /* |
---|
2 | * This file is produced automatically. |
---|
3 | * Do not modify anything in here by hand. |
---|
4 | * |
---|
5 | * Created from source file |
---|
6 | * freebsd-org/sys/kern/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 | |
---|
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 | |
---|
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 | |
---|
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 | |
---|
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 | |
---|
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 | |
---|
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 | |
---|
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 | |
---|
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 | |
---|
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_ */ |
---|