VirtualBox

source: vbox/trunk/include/VBox/vmm/pdmcommon.h@ 82261

Last change on this file since 82261 was 81369, checked in by vboxsync, 5 years ago

*: doxygen fixes

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 6.6 KB
Line 
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 */
117typedef DECLCALLBACK(bool) FNPDMUSBASYNCNOTIFY(PPDMUSBINS pUsbIns);
118/** Pointer to a FNPDMUSBASYNCNOTIFY. */
119typedef 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 */
133typedef DECLCALLBACK(bool) FNPDMDEVASYNCNOTIFY(PPDMDEVINS pDevIns);
134/** Pointer to a FNPDMDEVASYNCNOTIFY. */
135typedef 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 */
149typedef DECLCALLBACK(bool) FNPDMDRVASYNCNOTIFY(PPDMDRVINS pDrvIns);
150/** Pointer to a FNPDMDRVASYNCNOTIFY. */
151typedef 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 */
162typedef DECLCALLBACK(int) FNPDMDEVREQHANDLERR0(PPDMDEVINS pDevIns, uint32_t uOperation, uint64_t u64Arg);
163/** Ring-0 pointer to a FNPDMDEVREQHANDLERR0. */
164typedef 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 */
174typedef DECLCALLBACK(int) FNPDMDRVREQHANDLERR0(PPDMDRVINS pDrvIns, uint32_t uOperation, uint64_t u64Arg);
175/** Ring-0 pointer to a FNPDMDRVREQHANDLERR0. */
176typedef R0PTRTYPE(FNPDMDRVREQHANDLERR0 *) PFNPDMDRVREQHANDLERR0;
177
178
179/** @} */
180
181#endif /* !VBOX_INCLUDED_vmm_pdmcommon_h */
182
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