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