1 | /** @file
|
---|
2 | * PDM - Pluggable Device Manager.
|
---|
3 | */
|
---|
4 |
|
---|
5 | /*
|
---|
6 | * Copyright (C) 2006-2007 innotek GmbH
|
---|
7 | *
|
---|
8 | * This file is part of VirtualBox Open Source Edition (OSE), as
|
---|
9 | * available from http://www.virtualbox.org. This file is free software;
|
---|
10 | * you can redistribute it and/or modify it under the terms of the GNU
|
---|
11 | * General Public License as published by the Free Software Foundation,
|
---|
12 | * in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
|
---|
13 | * distribution. VirtualBox OSE is distributed in the hope that it will
|
---|
14 | * be useful, but WITHOUT ANY WARRANTY of any kind.
|
---|
15 | *
|
---|
16 | * If you received this file as part of a commercial VirtualBox
|
---|
17 | * distribution, then only the terms of your commercial VirtualBox
|
---|
18 | * license agreement apply instead of the previous paragraph.
|
---|
19 | */
|
---|
20 |
|
---|
21 | #ifndef ___VBox_pdm_h
|
---|
22 | #define ___VBox_pdm_h
|
---|
23 |
|
---|
24 | #include <VBox/pdmqueue.h>
|
---|
25 | #include <VBox/pdmcritsect.h>
|
---|
26 | #include <VBox/pdmthread.h>
|
---|
27 | #include <VBox/pdmifs.h>
|
---|
28 | #include <VBox/pdmdrv.h>
|
---|
29 | #include <VBox/pdmdev.h>
|
---|
30 | #include <VBox/pdmusb.h>
|
---|
31 | #include <VBox/pdmsrv.h>
|
---|
32 |
|
---|
33 | __BEGIN_DECLS
|
---|
34 |
|
---|
35 | /** @defgroup grp_pdm The Pluggable Device Manager API
|
---|
36 | * @{
|
---|
37 | */
|
---|
38 |
|
---|
39 | /** Source position.
|
---|
40 | * @deprecated Use RT_SRC_POS */
|
---|
41 | #define PDM_SRC_POS RT_SRC_POS
|
---|
42 |
|
---|
43 | /** Source position declaration.
|
---|
44 | * @deprecated Use RT_SRC_POS_DECL */
|
---|
45 | #define PDM_SRC_POS_DECL RT_SRC_POS_DECL
|
---|
46 |
|
---|
47 | /** Source position arguments.
|
---|
48 | * @deprecated Use RT_SRC_POS_ARGS */
|
---|
49 | #define PDM_SRC_POS_ARGS RT_SRC_POS_ARGS
|
---|
50 |
|
---|
51 |
|
---|
52 |
|
---|
53 | /**
|
---|
54 | * Gets the pending interrupt.
|
---|
55 | *
|
---|
56 | * @returns VBox status code.
|
---|
57 | * @param pVM VM handle.
|
---|
58 | * @param pu8Interrupt Where to store the interrupt on success.
|
---|
59 | */
|
---|
60 | PDMDECL(int) PDMGetInterrupt(PVM pVM, uint8_t *pu8Interrupt);
|
---|
61 |
|
---|
62 | /**
|
---|
63 | * Sets the pending ISA interrupt.
|
---|
64 | *
|
---|
65 | * @returns VBox status code.
|
---|
66 | * @param pVM VM handle.
|
---|
67 | * @param u8Irq The IRQ line.
|
---|
68 | * @param u8Level The new level. See the PDM_IRQ_LEVEL_* \#defines.
|
---|
69 | */
|
---|
70 | PDMDECL(int) PDMIsaSetIrq(PVM pVM, uint8_t u8Irq, uint8_t u8Level);
|
---|
71 |
|
---|
72 | /**
|
---|
73 | * Sets the pending I/O APIC interrupt.
|
---|
74 | *
|
---|
75 | * @returns VBox status code.
|
---|
76 | * @param pVM VM handle.
|
---|
77 | * @param u8Irq The IRQ line.
|
---|
78 | * @param u8Level The new level. See the PDM_IRQ_LEVEL_* \#defines.
|
---|
79 | */
|
---|
80 | PDMDECL(int) PDMIoApicSetIrq(PVM pVM, uint8_t u8Irq, uint8_t u8Level);
|
---|
81 |
|
---|
82 | /**
|
---|
83 | * Set the APIC base.
|
---|
84 | *
|
---|
85 | * @returns VBox status code.
|
---|
86 | * @param pVM VM handle.
|
---|
87 | * @param u64Base The new base.
|
---|
88 | */
|
---|
89 | PDMDECL(int) PDMApicSetBase(PVM pVM, uint64_t u64Base);
|
---|
90 |
|
---|
91 | /**
|
---|
92 | * Get the APIC base.
|
---|
93 | *
|
---|
94 | * @returns VBox status code.
|
---|
95 | * @param pVM VM handle.
|
---|
96 | * @param pu64Base Where to store the APIC base.
|
---|
97 | */
|
---|
98 | PDMDECL(int) PDMApicGetBase(PVM pVM, uint64_t *pu64Base);
|
---|
99 |
|
---|
100 | /**
|
---|
101 | * Set the TPR (task priority register?).
|
---|
102 | *
|
---|
103 | * @returns VBox status code.
|
---|
104 | * @param pVM VM handle.
|
---|
105 | * @param u8TPR The new TPR.
|
---|
106 | */
|
---|
107 | PDMDECL(int) PDMApicSetTPR(PVM pVM, uint8_t u8TPR);
|
---|
108 |
|
---|
109 | /**
|
---|
110 | * Get the TPR (task priority register?).
|
---|
111 | *
|
---|
112 | * @returns The current TPR.
|
---|
113 | * @param pVM VM handle.
|
---|
114 | * @param pu8TPR Where to store the TRP.
|
---|
115 | */
|
---|
116 | PDMDECL(int) PDMApicGetTPR(PVM pVM, uint8_t *pu8TPR);
|
---|
117 |
|
---|
118 |
|
---|
119 | #ifdef IN_RING3
|
---|
120 | /** @defgroup grp_pdm_r3 The PDM Host Context Ring-3 API
|
---|
121 | * @ingroup grp_pdm
|
---|
122 | * @{
|
---|
123 | */
|
---|
124 |
|
---|
125 | /**
|
---|
126 | * Initializes the PDM.
|
---|
127 | *
|
---|
128 | * @returns VBox status code.
|
---|
129 | * @param pVM The VM to operate on.
|
---|
130 | */
|
---|
131 | PDMR3DECL(int) PDMR3Init(PVM pVM);
|
---|
132 |
|
---|
133 | /**
|
---|
134 | * This function will notify all the devices and their
|
---|
135 | * attached drivers about the VM now being powered on.
|
---|
136 | *
|
---|
137 | * @param pVM VM Handle.
|
---|
138 | */
|
---|
139 | PDMR3DECL(void) PDMR3PowerOn(PVM pVM);
|
---|
140 |
|
---|
141 | /**
|
---|
142 | * This function will notify all the devices and their
|
---|
143 | * attached drivers about the VM now being reset.
|
---|
144 | *
|
---|
145 | * @param pVM VM Handle.
|
---|
146 | */
|
---|
147 | PDMR3DECL(void) PDMR3Reset(PVM pVM);
|
---|
148 |
|
---|
149 | /**
|
---|
150 | * This function will notify all the devices and their
|
---|
151 | * attached drivers about the VM now being suspended.
|
---|
152 | *
|
---|
153 | * @param pVM VM Handle.
|
---|
154 | */
|
---|
155 | PDMR3DECL(void) PDMR3Suspend(PVM pVM);
|
---|
156 |
|
---|
157 | /**
|
---|
158 | * This function will notify all the devices and their
|
---|
159 | * attached drivers about the VM now being resumed.
|
---|
160 | *
|
---|
161 | * @param pVM VM Handle.
|
---|
162 | */
|
---|
163 | PDMR3DECL(void) PDMR3Resume(PVM pVM);
|
---|
164 |
|
---|
165 | /**
|
---|
166 | * This function will notify all the devices and their
|
---|
167 | * attached drivers about the VM being powered off.
|
---|
168 | *
|
---|
169 | * @param pVM VM Handle.
|
---|
170 | */
|
---|
171 | PDMR3DECL(void) PDMR3PowerOff(PVM pVM);
|
---|
172 |
|
---|
173 |
|
---|
174 | /**
|
---|
175 | * Applies relocations to GC modules.
|
---|
176 | *
|
---|
177 | * This must be done very early in the relocation
|
---|
178 | * process so that components can resolve GC symbols during relocation.
|
---|
179 | *
|
---|
180 | * @param pVM VM handle.
|
---|
181 | * @param offDelta Relocation delta relative to old location.
|
---|
182 | */
|
---|
183 | PDMR3DECL(void) PDMR3LdrRelocate(PVM pVM, RTGCINTPTR offDelta);
|
---|
184 |
|
---|
185 | /**
|
---|
186 | * Applies relocations to data and code managed by this
|
---|
187 | * component. This function will be called at init and
|
---|
188 | * whenever the VMM need to relocate it self inside the GC.
|
---|
189 | *
|
---|
190 | * @param pVM VM handle.
|
---|
191 | * @param offDelta Relocation delta relative to old location.
|
---|
192 | */
|
---|
193 | PDMR3DECL(void) PDMR3Relocate(PVM pVM, RTGCINTPTR offDelta);
|
---|
194 |
|
---|
195 | /**
|
---|
196 | * Terminates the PDM.
|
---|
197 | *
|
---|
198 | * Termination means cleaning up and freeing all resources,
|
---|
199 | * the VM it self is at this point powered off or suspended.
|
---|
200 | *
|
---|
201 | * @returns VBox status code.
|
---|
202 | * @param pVM The VM to operate on.
|
---|
203 | */
|
---|
204 | PDMR3DECL(int) PDMR3Term(PVM pVM);
|
---|
205 |
|
---|
206 |
|
---|
207 | /**
|
---|
208 | * Get the address of a symbol in a given HC ring-3 module.
|
---|
209 | *
|
---|
210 | * @returns VBox status code.
|
---|
211 | * @param pVM VM handle.
|
---|
212 | * @param pszModule Module name.
|
---|
213 | * @param pszSymbol Symbol name. If it's value is less than 64k it's treated like a
|
---|
214 | * ordinal value rather than a string pointer.
|
---|
215 | * @param ppvValue Where to store the symbol value.
|
---|
216 | */
|
---|
217 | PDMR3DECL(int) PDMR3GetSymbolR3(PVM pVM, const char *pszModule, const char *pszSymbol, void **ppvValue);
|
---|
218 |
|
---|
219 | /**
|
---|
220 | * Get the address of a symbol in a given HC ring-0 module.
|
---|
221 | *
|
---|
222 | * @returns VBox status code.
|
---|
223 | * @param pVM VM handle.
|
---|
224 | * @param pszModule Module name. If NULL the main R0 module (VMMR0.r0) is assumed.
|
---|
225 | * @param pszSymbol Symbol name. If it's value is less than 64k it's treated like a
|
---|
226 | * ordinal value rather than a string pointer.
|
---|
227 | * @param ppvValue Where to store the symbol value.
|
---|
228 | */
|
---|
229 | PDMR3DECL(int) PDMR3GetSymbolR0(PVM pVM, const char *pszModule, const char *pszSymbol, PRTR0PTR ppvValue);
|
---|
230 |
|
---|
231 | /**
|
---|
232 | * Same as PDMR3GetSymbolR0 except that the module will be attempted loaded if not found.
|
---|
233 | *
|
---|
234 | * @returns VBox status code.
|
---|
235 | * @param pVM VM handle.
|
---|
236 | * @param pszModule Module name. If NULL the main R0 module (VMMR0.r0) is assumed.
|
---|
237 | * @param pszSymbol Symbol name. If it's value is less than 64k it's treated like a
|
---|
238 | * ordinal value rather than a string pointer.
|
---|
239 | * @param ppvValue Where to store the symbol value.
|
---|
240 | */
|
---|
241 | PDMR3DECL(int) PDMR3GetSymbolR0Lazy(PVM pVM, const char *pszModule, const char *pszSymbol, PRTR0PTR ppvValue);
|
---|
242 |
|
---|
243 | /**
|
---|
244 | * Loads a module into the guest context (i.e. into the Hypervisor memory region).
|
---|
245 | *
|
---|
246 | * The external (to PDM) use of this interface is to load VMMGC.gc.
|
---|
247 | *
|
---|
248 | * @returns VBox status code.
|
---|
249 | * @param pVM The VM to load it into.
|
---|
250 | * @param pszFilename Filename of the module binary.
|
---|
251 | * @param pszName Module name. Case sensitive and the length is limited!
|
---|
252 | */
|
---|
253 | PDMR3DECL(int) PDMR3LoadGC(PVM pVM, const char *pszFilename, const char *pszName);
|
---|
254 |
|
---|
255 | /**
|
---|
256 | * Get the address of a symbol in a given GC module.
|
---|
257 | *
|
---|
258 | * @returns VBox status code.
|
---|
259 | * @param pVM VM handle.
|
---|
260 | * @param pszModule Module name. If NULL the main GC module (VMMGC.gc) is assumed.
|
---|
261 | * @param pszSymbol Symbol name. If it's value is less than 64k it's treated like a
|
---|
262 | * ordinal value rather than a string pointer.
|
---|
263 | * @param pGCPtrValue Where to store the symbol value.
|
---|
264 | */
|
---|
265 | PDMR3DECL(int) PDMR3GetSymbolGC(PVM pVM, const char *pszModule, const char *pszSymbol, PRTGCPTR pGCPtrValue);
|
---|
266 |
|
---|
267 | /**
|
---|
268 | * Same as PDMR3GetSymbolGC except that the module will be attempted loaded if not found.
|
---|
269 | *
|
---|
270 | * @returns VBox status code.
|
---|
271 | * @param pVM VM handle.
|
---|
272 | * @param pszModule Module name. If NULL the main GC module (VMMGC.gc) is assumed.
|
---|
273 | * @param pszSymbol Symbol name. If it's value is less than 64k it's treated like a
|
---|
274 | * ordinal value rather than a string pointer.
|
---|
275 | * @param pGCPtrValue Where to store the symbol value.
|
---|
276 | */
|
---|
277 | PDMR3DECL(int) PDMR3GetSymbolGCLazy(PVM pVM, const char *pszModule, const char *pszSymbol, PRTGCPTR pGCPtrValue);
|
---|
278 |
|
---|
279 | /**
|
---|
280 | * Queries module information from an EIP.
|
---|
281 | *
|
---|
282 | * This is typically used to locate a crash address.
|
---|
283 | *
|
---|
284 | * @returns VBox status code.
|
---|
285 | * @param pVM VM handle
|
---|
286 | * @param uEIP EIP to locate.
|
---|
287 | * @param pszModName Where to store the module name.
|
---|
288 | * @param cchModName Size of the module name buffer.
|
---|
289 | * @param pMod Base address of the module.
|
---|
290 | * @param pszNearSym1 Name of the closes symbol from below.
|
---|
291 | * @param cchNearSym1 Size of the buffer pointed to by pszNearSym1.
|
---|
292 | * @param pNearSym1 The address of pszNearSym1.
|
---|
293 | * @param pszNearSym2 Name of the closes symbol from below.
|
---|
294 | * @param cchNearSym2 Size of the buffer pointed to by pszNearSym2.
|
---|
295 | * @param pNearSym2 The address of pszNearSym2.
|
---|
296 | */
|
---|
297 | PDMR3DECL(int) PDMR3QueryModFromEIP(PVM pVM, uint32_t uEIP,
|
---|
298 | char *pszModName, unsigned cchModName, RTGCPTR *pMod,
|
---|
299 | char *pszNearSym1, unsigned cchNearSym1, RTGCPTR *pNearSym1,
|
---|
300 | char *pszNearSym2, unsigned cchNearSym2, RTGCPTR *pNearSym2);
|
---|
301 |
|
---|
302 |
|
---|
303 | /**
|
---|
304 | * Module enumeration callback function.
|
---|
305 | *
|
---|
306 | * @returns VBox status.
|
---|
307 | * Failure will stop the search and return the return code.
|
---|
308 | * Warnings will be ignored and not returned.
|
---|
309 | * @param pVM VM Handle.
|
---|
310 | * @param pszFilename Module filename.
|
---|
311 | * @param pszName Module name. (short and unique)
|
---|
312 | * @param ImageBase Address where to executable image is loaded.
|
---|
313 | * @param cbImage Size of the executable image.
|
---|
314 | * @param fGC Set if guest context, clear if host context.
|
---|
315 | * @param pvArg User argument.
|
---|
316 | */
|
---|
317 | typedef DECLCALLBACK(int) FNPDMR3ENUM(PVM pVM, const char *pszFilename, const char *pszName, RTUINTPTR ImageBase, size_t cbImage, bool fGC);
|
---|
318 | /** Pointer to a FNPDMR3ENUM() function. */
|
---|
319 | typedef FNPDMR3ENUM *PFNPDMR3ENUM;
|
---|
320 |
|
---|
321 |
|
---|
322 | /**
|
---|
323 | * Enumerate all PDM modules.
|
---|
324 | *
|
---|
325 | * @returns VBox status.
|
---|
326 | * @param pVM VM Handle.
|
---|
327 | * @param pfnCallback Function to call back for each of the modules.
|
---|
328 | * @param pvArg User argument.
|
---|
329 | */
|
---|
330 | PDMR3DECL(int) PDMR3EnumModules(PVM pVM, PFNPDMR3ENUM pfnCallback, void *pvArg);
|
---|
331 |
|
---|
332 |
|
---|
333 | /**
|
---|
334 | * Queries the base interace of a device instance.
|
---|
335 | *
|
---|
336 | * The caller can use this to query other interfaces the device implements
|
---|
337 | * and use them to talk to the device.
|
---|
338 | *
|
---|
339 | * @returns VBox status code.
|
---|
340 | * @param pVM VM handle.
|
---|
341 | * @param pszDevice Device name.
|
---|
342 | * @param iInstance Device instance.
|
---|
343 | * @param ppBase Where to store the pointer to the base device interface on success.
|
---|
344 | * @remark We're not doing any locking ATM, so don't try call this at times when the
|
---|
345 | * device chain is known to be updated.
|
---|
346 | */
|
---|
347 | PDMR3DECL(int) PDMR3QueryDevice(PVM pVM, const char *pszDevice, unsigned iInstance, PPDMIBASE *ppBase);
|
---|
348 |
|
---|
349 | /**
|
---|
350 | * Queries the base interface of a device LUN.
|
---|
351 | *
|
---|
352 | * This differs from PDMR3QueryLun by that it returns the interface on the
|
---|
353 | * device and not the top level driver.
|
---|
354 | *
|
---|
355 | * @returns VBox status code.
|
---|
356 | * @param pVM VM Handle.
|
---|
357 | * @param pszDevice Device name.
|
---|
358 | * @param iInstance Device instance.
|
---|
359 | * @param iLun The Logical Unit to obtain the interface of.
|
---|
360 | * @param ppBase Where to store the base interface pointer.
|
---|
361 | * @remark We're not doing any locking ATM, so don't try call this at times when the
|
---|
362 | * device chain is known to be updated.
|
---|
363 | */
|
---|
364 | PDMR3DECL(int) PDMR3QueryDeviceLun(PVM pVM, const char *pszDevice, unsigned iInstance, unsigned iLun, PPDMIBASE *ppBase);
|
---|
365 |
|
---|
366 | /**
|
---|
367 | * Query the interface of the top level driver on a LUN.
|
---|
368 | *
|
---|
369 | * @returns VBox status code.
|
---|
370 | * @param pVM VM Handle.
|
---|
371 | * @param pszDevice Device name.
|
---|
372 | * @param iInstance Device instance.
|
---|
373 | * @param iLun The Logical Unit to obtain the interface of.
|
---|
374 | * @param ppBase Where to store the base interface pointer.
|
---|
375 | * @remark We're not doing any locking ATM, so don't try call this at times when the
|
---|
376 | * device chain is known to be updated.
|
---|
377 | */
|
---|
378 | PDMR3DECL(int) PDMR3QueryLun(PVM pVM, const char *pszDevice, unsigned iInstance, unsigned iLun, PPDMIBASE *ppBase);
|
---|
379 |
|
---|
380 | /**
|
---|
381 | * Attaches a preconfigured driver to an existing device instance.
|
---|
382 | *
|
---|
383 | * This is used to change drivers and suchlike at runtime.
|
---|
384 | *
|
---|
385 | * @returns VBox status code.
|
---|
386 | * @param pVM VM Handle.
|
---|
387 | * @param pszDevice Device name.
|
---|
388 | * @param iInstance Device instance.
|
---|
389 | * @param iLun The Logical Unit to obtain the interface of.
|
---|
390 | * @param ppBase Where to store the base interface pointer. Optional.
|
---|
391 | * @thread EMT
|
---|
392 | */
|
---|
393 | PDMR3DECL(int) PDMR3DeviceAttach(PVM pVM, const char *pszDevice, unsigned iInstance, unsigned iLun, PPDMIBASE *ppBase);
|
---|
394 |
|
---|
395 | /**
|
---|
396 | * Detaches a driver from an existing device instance.
|
---|
397 | *
|
---|
398 | * This is used to change drivers and suchlike at runtime.
|
---|
399 | *
|
---|
400 | * @returns VBox status code.
|
---|
401 | * @param pVM VM Handle.
|
---|
402 | * @param pszDevice Device name.
|
---|
403 | * @param iInstance Device instance.
|
---|
404 | * @param iLun The Logical Unit to obtain the interface of.
|
---|
405 | * @thread EMT
|
---|
406 | */
|
---|
407 | PDMR3DECL(int) PDMR3DeviceDetach(PVM pVM, const char *pszDevice, unsigned iInstance, unsigned iLun);
|
---|
408 |
|
---|
409 | /**
|
---|
410 | * Executes pending DMA transfers.
|
---|
411 | * Forced Action handler.
|
---|
412 | *
|
---|
413 | * @param pVM VM handle.
|
---|
414 | */
|
---|
415 | PDMR3DECL(void) PDMR3DmaRun(PVM pVM);
|
---|
416 |
|
---|
417 | /**
|
---|
418 | * Call polling function.
|
---|
419 | *
|
---|
420 | * @param pVM VM handle.
|
---|
421 | */
|
---|
422 | PDMR3DECL(void) PDMR3Poll(PVM pVM);
|
---|
423 |
|
---|
424 | /**
|
---|
425 | * Service a VMMCALLHOST_PDM_LOCK call.
|
---|
426 | *
|
---|
427 | * @returns VBox status code.
|
---|
428 | * @param pVM The VM handle.
|
---|
429 | */
|
---|
430 | PDMR3DECL(int) PDMR3LockCall(PVM pVM);
|
---|
431 |
|
---|
432 | /** @} */
|
---|
433 | #endif
|
---|
434 |
|
---|
435 |
|
---|
436 | #ifdef IN_GC
|
---|
437 | /** @defgroup grp_pdm_gc The PDM Guest Context API
|
---|
438 | * @ingroup grp_pdm
|
---|
439 | * @{
|
---|
440 | */
|
---|
441 | /** @} */
|
---|
442 | #endif
|
---|
443 |
|
---|
444 | __END_DECLS
|
---|
445 |
|
---|
446 | /** @} */
|
---|
447 |
|
---|
448 | #endif
|
---|
449 |
|
---|