VirtualBox

source: vbox/trunk/include/VBox/pdmapi.h@ 9569

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

More 64 bits guest preps

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