VirtualBox

source: vbox/trunk/include/VBox/pdm.h@ 4011

Last change on this file since 4011 was 4011, checked in by vboxsync, 17 years ago

fixed some header hacks.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 14.2 KB
Line 
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 */
60PDMDECL(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 */
70PDMDECL(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 */
80PDMDECL(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 */
89PDMDECL(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 */
98PDMDECL(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 */
107PDMDECL(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 */
116PDMDECL(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 */
131PDMR3DECL(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 */
139PDMR3DECL(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 */
147PDMR3DECL(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 */
155PDMR3DECL(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 */
163PDMR3DECL(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 */
171PDMR3DECL(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 */
183PDMR3DECL(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 */
193PDMR3DECL(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 */
204PDMR3DECL(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 */
217PDMR3DECL(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 */
229PDMR3DECL(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 */
241PDMR3DECL(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 */
253PDMR3DECL(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 */
265PDMR3DECL(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 */
277PDMR3DECL(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 */
297PDMR3DECL(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 */
317typedef DECLCALLBACK(int) FNPDMR3ENUM(PVM pVM, const char *pszFilename, const char *pszName, RTUINTPTR ImageBase, size_t cbImage, bool fGC);
318/** Pointer to a FNPDMR3ENUM() function. */
319typedef 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 */
330PDMR3DECL(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 */
347PDMR3DECL(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 */
364PDMR3DECL(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 */
378PDMR3DECL(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 */
393PDMR3DECL(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 */
407PDMR3DECL(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 */
415PDMR3DECL(void) PDMR3DmaRun(PVM pVM);
416
417/**
418 * Call polling function.
419 *
420 * @param pVM VM handle.
421 */
422PDMR3DECL(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 */
430PDMR3DECL(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
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette