VirtualBox

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

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

pdm.h = include pdm*.h; pdmapi.h = only the 'core' pdm APIs.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 13.9 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 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 */
43PDMDECL(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 */
53PDMDECL(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 */
63PDMDECL(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 */
72PDMDECL(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 */
81PDMDECL(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 */
90PDMDECL(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 */
99PDMDECL(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 */
114PDMR3DECL(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 */
122PDMR3DECL(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 */
130PDMR3DECL(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 */
138PDMR3DECL(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 */
146PDMR3DECL(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 */
154PDMR3DECL(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 */
166PDMR3DECL(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 */
176PDMR3DECL(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 */
187PDMR3DECL(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 */
200PDMR3DECL(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 */
212PDMR3DECL(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 */
224PDMR3DECL(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 */
236PDMR3DECL(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 */
248PDMR3DECL(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 */
260PDMR3DECL(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 */
280PDMR3DECL(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 */
300typedef DECLCALLBACK(int) FNPDMR3ENUM(PVM pVM, const char *pszFilename, const char *pszName, RTUINTPTR ImageBase, size_t cbImage, bool fGC);
301/** Pointer to a FNPDMR3ENUM() function. */
302typedef 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 */
313PDMR3DECL(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 */
330PDMR3DECL(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 */
347PDMR3DECL(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 */
361PDMR3DECL(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 */
376PDMR3DECL(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 */
390PDMR3DECL(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 */
398PDMR3DECL(void) PDMR3DmaRun(PVM pVM);
399
400/**
401 * Call polling function.
402 *
403 * @param pVM VM handle.
404 */
405PDMR3DECL(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 */
413PDMR3DECL(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
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