1 | /** @file
|
---|
2 | * PDM - Pluggable Device Manager, Common Definitions & Types.
|
---|
3 | */
|
---|
4 |
|
---|
5 | /*
|
---|
6 | * Copyright (C) 2006-2019 Oracle Corporation
|
---|
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 |
|
---|
26 | #ifndef VBOX_INCLUDED_vmm_pdmcommon_h
|
---|
27 | #define VBOX_INCLUDED_vmm_pdmcommon_h
|
---|
28 | #ifndef RT_WITHOUT_PRAGMA_ONCE
|
---|
29 | # pragma once
|
---|
30 | #endif
|
---|
31 |
|
---|
32 | #include <VBox/types.h>
|
---|
33 |
|
---|
34 |
|
---|
35 | /** @defgroup grp_pdm_common Common Definitions & Types
|
---|
36 | * @ingroup grp_pdm
|
---|
37 | *
|
---|
38 | * Not all the types here are "common", they are here to work around header
|
---|
39 | * ordering issues.
|
---|
40 | *
|
---|
41 | * @{
|
---|
42 | */
|
---|
43 |
|
---|
44 | /** Makes a PDM structure version out of an unique magic value and major &
|
---|
45 | * minor version numbers.
|
---|
46 | *
|
---|
47 | * @returns 32-bit structure version number.
|
---|
48 | *
|
---|
49 | * @param uMagic 16-bit magic value. This must be unique.
|
---|
50 | * @param uMajor 12-bit major version number. Structures with different
|
---|
51 | * major numbers are not compatible.
|
---|
52 | * @param uMinor 4-bit minor version number. When only the minor version
|
---|
53 | * differs, the structures will be 100% backwards
|
---|
54 | * compatible.
|
---|
55 | */
|
---|
56 | #define PDM_VERSION_MAKE(uMagic, uMajor, uMinor) \
|
---|
57 | ( ((uint32_t)(uMagic) << 16) | ((uint32_t)((uMajor) & 0xff) << 4) | ((uint32_t)((uMinor) & 0xf) << 0) )
|
---|
58 |
|
---|
59 | /**
|
---|
60 | * Version of PDM_VERSION_MAKE that's compatible with the preprocessor.
|
---|
61 | *
|
---|
62 | * @returns 32-bit structure version number.
|
---|
63 | *
|
---|
64 | * @param uMagic 16-bit magic value, no suffix. This must be unique.
|
---|
65 | * @param uMajor 12-bit major version number, no suffix. Structures with
|
---|
66 | * different major numbers are not compatible.
|
---|
67 | * @param uMinor 4-bit minor version number, no suffix. When only the
|
---|
68 | * minor version differs, the structures will be 100%
|
---|
69 | * backwards compatible.
|
---|
70 | */
|
---|
71 | #define PDM_VERSION_MAKE_PP(uMagic, uMajor, uMinor) \
|
---|
72 | ( (UINT32_C(uMagic) << 16) | ((UINT32_C(uMajor) & UINT32_C(0xff)) << 4) | ((UINT32_C(uMinor) & UINT32_C(0xf)) << 0) )
|
---|
73 |
|
---|
74 | /** Checks if @a uVerMagic1 is compatible with @a uVerMagic2.
|
---|
75 | *
|
---|
76 | * @returns true / false.
|
---|
77 | * @param uVerMagic1 Typically the runtime version of the struct. This must
|
---|
78 | * have the same magic and major version as @a uVerMagic2
|
---|
79 | * and the minor version must be greater or equal to that
|
---|
80 | * of @a uVerMagic2.
|
---|
81 | * @param uVerMagic2 Typically the version the code was compiled against.
|
---|
82 | *
|
---|
83 | * @remarks The parameters will be referenced more than once.
|
---|
84 | */
|
---|
85 | #define PDM_VERSION_ARE_COMPATIBLE(uVerMagic1, uVerMagic2) \
|
---|
86 | ( (uVerMagic1) == (uVerMagic2) \
|
---|
87 | || ( (uVerMagic1) >= (uVerMagic2) \
|
---|
88 | && ((uVerMagic1) & UINT32_C(0xfffffff0)) == ((uVerMagic2) & UINT32_C(0xfffffff0)) ) \
|
---|
89 | )
|
---|
90 |
|
---|
91 |
|
---|
92 | /** @name PDM Attach/Detach Callback Flags.
|
---|
93 | * Used by PDMDeviceAttach, PDMDeviceDetach, PDMDriverAttach, PDMDriverDetach,
|
---|
94 | * FNPDMDEVATTACH, FNPDMDEVDETACH, FNPDMDRVATTACH, FNPDMDRVDETACH and
|
---|
95 | * FNPDMDRVCONSTRUCT.
|
---|
96 | * @{ */
|
---|
97 | /** The attach/detach command is not a hotplug event. */
|
---|
98 | #define PDM_TACH_FLAGS_NOT_HOT_PLUG RT_BIT_32(0)
|
---|
99 | /** Indicates that no attach or detach callbacks should be made.
|
---|
100 | * This is mostly for internal use. */
|
---|
101 | #define PDM_TACH_FLAGS_NO_CALLBACKS RT_BIT_32(1)
|
---|
102 | /** @} */
|
---|
103 |
|
---|
104 |
|
---|
105 | /**
|
---|
106 | * Is asynchronous handling of suspend or power off notification completed?
|
---|
107 | *
|
---|
108 | * This is called to check whether the USB device has quiesced. Don't deadlock.
|
---|
109 | * Avoid blocking. Do NOT wait for anything.
|
---|
110 | *
|
---|
111 | * @returns true if done, false if more work to be done.
|
---|
112 | *
|
---|
113 | * @param pUsbIns The USB device instance.
|
---|
114 | *
|
---|
115 | * @thread EMT(0)
|
---|
116 | */
|
---|
117 | typedef DECLCALLBACK(bool) FNPDMUSBASYNCNOTIFY(PPDMUSBINS pUsbIns);
|
---|
118 | /** Pointer to a FNPDMUSBASYNCNOTIFY. */
|
---|
119 | typedef FNPDMUSBASYNCNOTIFY *PFNPDMUSBASYNCNOTIFY;
|
---|
120 |
|
---|
121 | /**
|
---|
122 | * Is asynchronous handling of suspend or power off notification completed?
|
---|
123 | *
|
---|
124 | * This is called to check whether the device has quiesced. Don't deadlock.
|
---|
125 | * Avoid blocking. Do NOT wait for anything.
|
---|
126 | *
|
---|
127 | * @returns true if done, false if more work to be done.
|
---|
128 | *
|
---|
129 | * @param pDevIns The device instance.
|
---|
130 | * @remarks The caller will enter the device critical section.
|
---|
131 | * @thread EMT(0)
|
---|
132 | */
|
---|
133 | typedef DECLCALLBACK(bool) FNPDMDEVASYNCNOTIFY(PPDMDEVINS pDevIns);
|
---|
134 | /** Pointer to a FNPDMDEVASYNCNOTIFY. */
|
---|
135 | typedef FNPDMDEVASYNCNOTIFY *PFNPDMDEVASYNCNOTIFY;
|
---|
136 |
|
---|
137 | /**
|
---|
138 | * Is asynchronous handling of suspend or power off notification completed?
|
---|
139 | *
|
---|
140 | * This is called to check whether the driver has quiesced. Don't deadlock.
|
---|
141 | * Avoid blocking. Do NOT wait for anything.
|
---|
142 | *
|
---|
143 | * @returns true if done, false if more work to be done.
|
---|
144 | *
|
---|
145 | * @param pDrvIns The driver instance.
|
---|
146 | *
|
---|
147 | * @thread EMT(0)
|
---|
148 | */
|
---|
149 | typedef DECLCALLBACK(bool) FNPDMDRVASYNCNOTIFY(PPDMDRVINS pDrvIns);
|
---|
150 | /** Pointer to a FNPDMDRVASYNCNOTIFY. */
|
---|
151 | typedef FNPDMDRVASYNCNOTIFY *PFNPDMDRVASYNCNOTIFY;
|
---|
152 |
|
---|
153 |
|
---|
154 | /**
|
---|
155 | * The ring-0 driver request handler.
|
---|
156 | *
|
---|
157 | * @returns VBox status code. PDMDevHlpCallR0 will return this.
|
---|
158 | * @param pDevIns The device instance (the ring-0 mapping).
|
---|
159 | * @param uOperation The operation.
|
---|
160 | * @param u64Arg Optional integer argument for the operation.
|
---|
161 | */
|
---|
162 | typedef DECLCALLBACK(int) FNPDMDEVREQHANDLERR0(PPDMDEVINS pDevIns, uint32_t uOperation, uint64_t u64Arg);
|
---|
163 | /** Ring-0 pointer to a FNPDMDEVREQHANDLERR0. */
|
---|
164 | typedef R0PTRTYPE(FNPDMDEVREQHANDLERR0 *) PFNPDMDEVREQHANDLERR0;
|
---|
165 |
|
---|
166 | /**
|
---|
167 | * The ring-0 driver request handler.
|
---|
168 | *
|
---|
169 | * @returns VBox status code. PDMDrvHlpCallR0 will return this.
|
---|
170 | * @param pDrvIns The driver instance (the ring-0 mapping).
|
---|
171 | * @param uOperation The operation.
|
---|
172 | * @param u64Arg Optional integer argument for the operation.
|
---|
173 | */
|
---|
174 | typedef DECLCALLBACK(int) FNPDMDRVREQHANDLERR0(PPDMDRVINS pDrvIns, uint32_t uOperation, uint64_t u64Arg);
|
---|
175 | /** Ring-0 pointer to a FNPDMDRVREQHANDLERR0. */
|
---|
176 | typedef R0PTRTYPE(FNPDMDRVREQHANDLERR0 *) PFNPDMDRVREQHANDLERR0;
|
---|
177 |
|
---|
178 |
|
---|
179 | /** @} */
|
---|
180 |
|
---|
181 | #endif /* !VBOX_INCLUDED_vmm_pdmcommon_h */
|
---|
182 |
|
---|