VirtualBox

source: vbox/trunk/include/VBox/vmm/pdmsrv.h@ 76198

Last change on this file since 76198 was 73097, checked in by vboxsync, 6 years ago

*: Made RT_UOFFSETOF, RT_OFFSETOF, RT_UOFFSETOF_ADD and RT_OFFSETOF_ADD work like builtin_offsetof() and require compile time resolvable requests, adding RT_UOFFSETOF_DYN for the dynamic questions that can only be answered at runtime.

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