VirtualBox

source: vbox/trunk/include/VBox/pdmsrv.h@ 18566

Last change on this file since 18566 was 13005, checked in by vboxsync, 16 years ago

VMM/doxygen: More links.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 11.0 KB
Line 
1/** @file
2 * PDM - Pluggable Device Manager, VM Services.
3 */
4
5/*
6 * Copyright (C) 2006-2007 Sun Microsystems, Inc.
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 (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 *
25 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
26 * Clara, CA 95054 USA or visit http://www.sun.com if you need
27 * additional information or have any questions.
28 */
29
30#ifndef ___VBox_pdmsrv_h
31#define ___VBox_pdmsrv_h
32
33#include <VBox/pdmifs.h>
34#include <VBox/ssm.h>
35#include <VBox/cfgm.h>
36
37__BEGIN_DECLS
38
39/** @defgroup grp_pdm_services The PDM Services API
40 * @ingroup grp_pdm
41 * @{
42 */
43
44/**
45 * Construct a service instance for a VM.
46 *
47 * @returns VBox status.
48 * @param pSrvIns The service instance data.
49 * If the registration structure is needed, pSrvIns->pReg points to it.
50 * @param pCfg Configuration node handle for the service. Use this to obtain the configuration
51 * of the driver instance. It's also found in pSrvIns->pCfg, but since it's primary
52 * usage is expected in this function it is passed as a parameter.
53 */
54typedef DECLCALLBACK(int) FNPDMSRVCONSTRUCT(PPDMSRVINS pSrvIns, PCFGMNODE pCfg);
55/** Pointer to a FNPDMSRVCONSTRUCT() function. */
56typedef FNPDMSRVCONSTRUCT *PFNPDMSRVCONSTRUCT;
57
58/**
59 * Destruct a driver instance.
60 *
61 * Most VM resources are freed by the VM. This callback is provided so that any non-VM
62 * resources can be freed correctly.
63 *
64 * @param pSrvIns The service instance data.
65 */
66typedef DECLCALLBACK(void) FNPDMSRVDESTRUCT(PPDMSRVINS pSrvIns);
67/** Pointer to a FNPDMSRVDESTRUCT() function. */
68typedef FNPDMSRVDESTRUCT *PFNPDMSRVDESTRUCT;
69
70/**
71 * Power On notification.
72 *
73 * @param pSrvIns The service instance data.
74 */
75typedef DECLCALLBACK(void) FNPDMSRVPOWERON(PPDMSRVINS pSrvIns);
76/** Pointer to a FNPDMSRVPOWERON() function. */
77typedef FNPDMSRVPOWERON *PFNPDMSRVPOWERON;
78
79/**
80 * Reset notification.
81 *
82 * @returns VBox status.
83 * @param pSrvIns The service instance data.
84 */
85typedef DECLCALLBACK(void) FNPDMSRVRESET(PPDMSRVINS pSrvIns);
86/** Pointer to a FNPDMSRVRESET() function. */
87typedef FNPDMSRVRESET *PFNPDMSRVRESET;
88
89/**
90 * Suspend notification.
91 *
92 * @returns VBox status.
93 * @param pSrvIns The service instance data.
94 */
95typedef DECLCALLBACK(void) FNPDMSRVSUSPEND(PPDMSRVINS pSrvIns);
96/** Pointer to a FNPDMSRVSUSPEND() function. */
97typedef FNPDMSRVSUSPEND *PFNPDMSRVSUSPEND;
98
99/**
100 * Resume notification.
101 *
102 * @returns VBox status.
103 * @param pSrvIns The service instance data.
104 */
105typedef DECLCALLBACK(void) FNPDMSRVRESUME(PPDMSRVINS pSrvIns);
106/** Pointer to a FNPDMSRVRESUME() function. */
107typedef FNPDMSRVRESUME *PFNPDMSRVRESUME;
108
109/**
110 * Power Off notification.
111 *
112 * @param pSrvIns The service instance data.
113 */
114typedef DECLCALLBACK(void) FNPDMSRVPOWEROFF(PPDMSRVINS pSrvIns);
115/** Pointer to a FNPDMSRVPOWEROFF() function. */
116typedef FNPDMSRVPOWEROFF *PFNPDMSRVPOWEROFF;
117
118/**
119 * Detach notification.
120 *
121 * This is called when a driver or device is detached from the service
122 *
123 * @param pSrvIns The service instance data.
124 */
125typedef DECLCALLBACK(void) FNPDMSRVDETACH(PPDMSRVINS pSrvIns, PPDMDEVINS pDevIns, PPDMDRVINS pDrvIns);
126/** Pointer to a FNPDMSRVDETACH() function. */
127typedef FNPDMSRVDETACH *PFNPDMSRVDETACH;
128
129
130
131/** PDM Service Registration Structure,
132 * This structure is used when registering a driver from
133 * VBoxServicesRegister() (HC Ring-3). PDM will continue use till
134 * the VM is terminated.
135 */
136typedef struct PDMSRVREG
137{
138 /** Structure version. PDM_SRVREG_VERSION defines the current version. */
139 uint32_t u32Version;
140 /** Driver name. */
141 char szServiceName[32];
142 /** The description of the driver. The UTF-8 string pointed to shall, like this structure,
143 * remain unchanged from registration till VM destruction. */
144 const char *pszDescription;
145
146 /** Flags, combination of the PDM_SRVREG_FLAGS_* \#defines. */
147 RTUINT fFlags;
148 /** Size of the instance data. */
149 RTUINT cbInstance;
150
151 /** Construct instance - required. */
152 PFNPDMSRVCONSTRUCT pfnConstruct;
153 /** Destruct instance - optional. */
154 PFNPDMSRVDESTRUCT pfnDestruct;
155 /** Power on notification - optional. */
156 PFNPDMSRVPOWERON pfnPowerOn;
157 /** Reset notification - optional. */
158 PFNPDMSRVRESET pfnReset;
159 /** Suspend notification - optional. */
160 PFNPDMSRVSUSPEND pfnSuspend;
161 /** Resume notification - optional. */
162 PFNPDMSRVRESUME pfnResume;
163 /** Detach notification - optional. */
164 PFNPDMSRVDETACH pfnDetach;
165 /** Power off notification - optional. */
166 PFNPDMSRVPOWEROFF pfnPowerOff;
167
168} PDMSRVREG;
169/** Pointer to a PDM Driver Structure. */
170typedef PDMSRVREG *PPDMSRVREG;
171/** Const pointer to a PDM Driver Structure. */
172typedef PDMSRVREG const *PCPDMSRVREG;
173
174
175
176/**
177 * PDM Service API.
178 */
179typedef struct PDMSRVHLP
180{
181 /** Structure version. PDM_SRVHLP_VERSION defines the current version. */
182 uint32_t u32Version;
183
184 /**
185 * Assert that the current thread is the emulation thread.
186 *
187 * @returns True if correct.
188 * @returns False if wrong.
189 * @param pSrvIns Service instance.
190 * @param pszFile Filename of the assertion location.
191 * @param iLine Linenumber of the assertion location.
192 * @param pszFunction Function of the assertion location.
193 */
194 DECLR3CALLBACKMEMBER(bool, pfnAssertEMT,(PPDMSRVINS pSrvIns, const char *pszFile, unsigned iLine, const char *pszFunction));
195
196 /**
197 * Assert that the current thread is NOT the emulation thread.
198 *
199 * @returns True if correct.
200 * @returns False if wrong.
201 * @param pSrvIns Service instance.
202 * @param pszFile Filename of the assertion location.
203 * @param iLine Linenumber of the assertion location.
204 * @param pszFunction Function of the assertion location.
205 */
206 DECLR3CALLBACKMEMBER(bool, pfnAssertOther,(PPDMSRVINS pSrvIns, const char *pszFile, unsigned iLine, const char *pszFunction));
207
208 /**
209 * Creates a timer.
210 *
211 * @returns VBox status.
212 * @param pVM The VM to create the timer in.
213 * @param pSrvIns Service instance.
214 * @param enmClock The clock to use on this timer.
215 * @param pfnCallback Callback function.
216 * @param pszDesc Pointer to description string which must stay around
217 * until the timer is fully destroyed (i.e. a bit after TMTimerDestroy()).
218 * @param ppTimer Where to store the timer on success.
219 */
220 DECLR3CALLBACKMEMBER(int, pfnTMTimerCreate,(PPDMSRVINS pSrvIns, TMCLOCK enmClock, PFNTMTIMERDEV pfnCallback, const char *pszDesc, PPTMTIMERR3 ppTimer));
221
222 /**
223 * Query the virtual timer frequency.
224 *
225 * @returns Frequency in Hz.
226 * @param pSrvIns Service instance.
227 * @thread Any thread.
228 */
229 DECLR3CALLBACKMEMBER(uint64_t, pfnTMGetVirtualFreq,(PPDMSRVINS pSrvIns));
230
231 /**
232 * Query the virtual time.
233 *
234 * @returns The current virtual time.
235 * @param pSrvIns Service instance.
236 * @thread Any thread.
237 */
238 DECLR3CALLBACKMEMBER(uint64_t, pfnTMGetVirtualTime,(PPDMSRVINS pSrvIns));
239
240} PDMSRVHLP;
241/** Pointer PDM Service API. */
242typedef PDMSRVHLP *PPDMSRVHLP;
243/** Pointer const PDM Service API. */
244typedef const PDMSRVHLP *PCPDMSRVHLP;
245
246/** Current SRVHLP version number. */
247#define PDM_SRVHLP_VERSION 0xf9010000
248
249
250/**
251 * PDM Service Instance.
252 */
253typedef struct PDMSRVINS
254{
255 /** Structure version. PDM_SRVINS_VERSION defines the current version. */
256 uint32_t u32Version;
257
258 /** Internal data. */
259 union
260 {
261#ifdef PDMSRVINSINT_DECLARED
262 PDMSRVINSINT s;
263#endif
264 uint8_t padding[HC_ARCH_BITS == 32 ? 32 : 32];
265 } Internal;
266
267 /** Pointer the PDM Service API. */
268 R3PTRTYPE(PCPDMSRVHLP) pHlp;
269 /** Pointer to driver registration structure. */
270 R3PTRTYPE(PCPDMSRVREG) pReg;
271 /** Configuration handle. */
272 R3PTRTYPE(PCFGMNODE) pCfg;
273 /** The base interface of the service.
274 * The service constructor initializes this. */
275 PDMIBASE IBase;
276 /* padding to make achInstanceData aligned at 16 byte boundrary. */
277 uint32_t au32Padding[2];
278 /** Pointer to driver instance data. */
279 R3PTRTYPE(void *) pvInstanceData;
280 /** Driver instance data. The size of this area is defined
281 * in the PDMSRVREG::cbInstanceData field. */
282 char achInstanceData[4];
283} PDMSRVINS;
284
285/** Current PDMSRVREG version number. */
286#define PDM_SRVINS_VERSION 0xf7010000
287
288/** Converts a pointer to the PDMSRVINS::IBase to a pointer to PDMSRVINS. */
289#define PDMIBASE_2_PDMSRV(pInterface) ( (PPDMSRVINS)((char *)(pInterface) - RT_OFFSETOF(PDMSRVINS, IBase)) )
290
291
292
293/** Pointer to callbacks provided to the VBoxServiceRegister() call. */
294typedef struct PDMSRVREGCB *PPDMSRVREGCB;
295
296/**
297 * Callbacks for VBoxServiceRegister().
298 */
299typedef struct PDMSRVREGCB
300{
301 /** Interface version.
302 * This is set to PDM_SRVREG_CB_VERSION. */
303 uint32_t u32Version;
304
305 /**
306 * Registers a service with the current VM instance.
307 *
308 * @returns VBox status code.
309 * @param pCallbacks Pointer to the callback table.
310 * @param pSrvReg Pointer to the device registration record.
311 * This data must be permanent and readonly.
312 */
313 DECLR3CALLBACKMEMBER(int, pfnRegister,(PPDMSRVREGCB pCallbacks, PCPDMSRVREG pSrvReg));
314} PDMSRVREGCB;
315
316/** Current version of the PDMSRVREGCB structure. */
317#define PDM_SRVREG_CB_VERSION 0xf8010000
318
319
320/**
321 * The VBoxServicesRegister callback function.
322 *
323 * PDM will invoke this function after loading a device module and letting
324 * the module decide which devices to register and how to handle conflicts.
325 *
326 * @returns VBox status code.
327 * @param pCallbacks Pointer to the callback table.
328 * @param u32Version VBox version number.
329 */
330typedef DECLCALLBACK(int) FNPDMVBOXSERVICESREGISTER(PPDMSRVREGCB pCallbacks, uint32_t u32Version);
331
332
333/** @} */
334
335__END_DECLS
336
337#endif
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