iom.h@ 58650

Last change on this file since 58650 was 58110, checked in by vboxsync, 9 years ago
include,misc: Doxygen grouping adjustments, collecting all the VMM bits under one parent group, ditto for the COM library.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 16.9 KB

Line
1	/** @file
2	* IOM - Input / Output Monitor.
3	*/
4
5	/*
6	* Copyright (C) 2006-2015 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_vmm_iom_h
27	#define ___VBox_vmm_iom_h
28
29	#include <VBox/types.h>
30	#include <VBox/dis.h>
31
32	RT_C_DECLS_BEGIN
33
34
35	/** @defgroup grp_iom The Input / Ouput Monitor API
36	* @ingroup grp_vmm
37	* @{
38	*/
39
40	/** @def IOM_NO_PDMINS_CHECKS
41	* Until all devices have been fully adjusted to PDM style, the pPdmIns
42	* parameter is not checked by IOM.
43	* @todo Check this again, now.
44	*/
45	#define IOM_NO_PDMINS_CHECKS
46
47	/**
48	* Macro for checking if an I/O or MMIO emulation call succeeded.
49	*
50	* This macro shall only be used with the IOM APIs where it's mentioned
51	* in the return value description. And there it must be used to correctly
52	* determine if the call succeeded and things like the RIP needs updating.
53	*
54	*
55	* @returns Success indicator (true/false).
56	*
57	* @param rc The status code. This may be evaluated
58	* more than once!
59	*
60	* @remark To avoid making assumptions about the layout of the
61	* VINF_EM_FIRST...VINF_EM_LAST range we're checking explicitly for
62	* each exact exception. However, for efficiency we ASSUME that the
63	* VINF_EM_LAST is smaller than most of the relevant status codes. We
64	* also ASSUME that the VINF_EM_RESCHEDULE_REM status code is the
65	* most frequent status code we'll enounter in this range.
66	*
67	* @todo Will have to add VINF_EM_DBG_HYPER_BREAKPOINT if the
68	* I/O port and MMIO breakpoints should trigger before
69	* the I/O is done. Currently, we don't implement these
70	* kind of breakpoints.
71	*/
72	#define IOM_SUCCESS(rc) ( (rc) == VINF_SUCCESS \
73	\|\| ( (rc) <= VINF_EM_LAST \
74	&& (rc) != VINF_EM_RESCHEDULE_REM \
75	&& (rc) >= VINF_EM_FIRST \
76	&& (rc) != VINF_EM_RESCHEDULE_RAW \
77	&& (rc) != VINF_EM_RESCHEDULE_HM \
78	) \
79	)
80
81	/** @name IOMMMIO_FLAGS_XXX
82	* @{ */
83	/** Pass all reads thru unmodified. */
84	#define IOMMMIO_FLAGS_READ_PASSTHRU UINT32_C(0x00000000)
85	/** All read accesses are DWORD sized (32-bit). */
86	#define IOMMMIO_FLAGS_READ_DWORD UINT32_C(0x00000001)
87	/** All read accesses are DWORD (32-bit) or QWORD (64-bit) sized.
88	* Only accesses that are both QWORD sized and aligned are performed as QWORD.
89	* All other access will be done DWORD fashion (because it is way simpler). */
90	#define IOMMMIO_FLAGS_READ_DWORD_QWORD UINT32_C(0x00000002)
91	/** The read access mode mask. */
92	#define IOMMMIO_FLAGS_READ_MODE UINT32_C(0x00000003)
93
94	/** Pass all writes thru unmodified. */
95	#define IOMMMIO_FLAGS_WRITE_PASSTHRU UINT32_C(0x00000000)
96	/** All write accesses are DWORD (32-bit) sized and unspecified bytes are
97	* written as zero. */
98	#define IOMMMIO_FLAGS_WRITE_DWORD_ZEROED UINT32_C(0x00000010)
99	/** All write accesses are either DWORD (32-bit) or QWORD (64-bit) sized,
100	* missing bytes will be written as zero. Only accesses that are both QWORD
101	* sized and aligned are performed as QWORD, all other accesses will be done
102	* DWORD fashion (because it's way simpler). */
103	#define IOMMMIO_FLAGS_WRITE_DWORD_QWORD_ZEROED UINT32_C(0x00000020)
104	/** All write accesses are DWORD (32-bit) sized and unspecified bytes are
105	* read from the device first as DWORDs.
106	* @remarks This isn't how it happens on real hardware, but it allows
107	* simplifications of devices where reads doesn't change the device
108	* state in any way. */
109	#define IOMMMIO_FLAGS_WRITE_DWORD_READ_MISSING UINT32_C(0x00000030)
110	/** All write accesses are DWORD (32-bit) or QWORD (64-bit) sized and
111	* unspecified bytes are read from the device first as DWORDs. Only accesses
112	* that are both QWORD sized and aligned are performed as QWORD, all other
113	* accesses will be done DWORD fashion (because it's way simpler).
114	* @remarks This isn't how it happens on real hardware, but it allows
115	* simplifications of devices where reads doesn't change the device
116	* state in any way. */
117	#define IOMMMIO_FLAGS_WRITE_DWORD_QWORD_READ_MISSING UINT32_C(0x00000040)
118	/** All write accesses are DWORD (32-bit) sized and aligned, attempts at other
119	* accesses are ignored.
120	* @remarks E1000, APIC */
121	#define IOMMMIO_FLAGS_WRITE_ONLY_DWORD UINT32_C(0x00000050)
122	/** All write accesses are DWORD (32-bit) or QWORD (64-bit) sized and aligned,
123	* attempts at other accesses are ignored.
124	* @remarks Seemingly required by AHCI (although I doubt it's _really_
125	* required as EM/REM doesn't do the right thing in ring-3 anyway,
126	* esp. not in raw-mode). */
127	#define IOMMMIO_FLAGS_WRITE_ONLY_DWORD_QWORD UINT32_C(0x00000060)
128	/** The read access mode mask. */
129	#define IOMMMIO_FLAGS_WRITE_MODE UINT32_C(0x00000070)
130
131	/** Whether to do a DBGSTOP on complicated reads.
132	* What this includes depends on the read mode, but generally all misaligned
133	* reads as well as word and byte reads and maybe qword reads. */
134	#define IOMMMIO_FLAGS_DBGSTOP_ON_COMPLICATED_READ UINT32_C(0x00000100)
135	/** Whether to do a DBGSTOP on complicated writes.
136	* This depends on the write mode, but generally all writes where we have to
137	* supply bytes (zero them or read them). */
138	#define IOMMMIO_FLAGS_DBGSTOP_ON_COMPLICATED_WRITE UINT32_C(0x00000200)
139
140	/** Mask of valid flags. */
141	#define IOMMMIO_FLAGS_VALID_MASK UINT32_C(0x00000373)
142	/** @} */
143
144	/**
145	* Checks whether the write mode allows aligned QWORD accesses to be passed
146	* thru to the device handler.
147	* @param a_fFlags The MMIO handler flags.
148	* @remarks The current implementation makes ASSUMPTIONS about the mode values!
149	*/
150	#define IOMMMIO_DOES_WRITE_MODE_ALLOW_QWORD(a_fFlags) RT_BOOL((a_fFlags) & UINT32_C(0x00000020))
151
152
153	/**
154	* Port I/O Handler for IN operations.
155	*
156	* @returns VINF_SUCCESS or VINF_EM_*.
157	* @returns VERR_IOM_IOPORT_UNUSED if the port is really unused and a ~0 value should be returned.
158	*
159	* @param pDevIns The device instance.
160	* @param pvUser User argument.
161	* @param uPort Port number used for the IN operation.
162	* @param pu32 Where to store the result. This is always a 32-bit
163	* variable regardless of what @a cb might say.
164	* @param cb Number of bytes read.
165	* @remarks Caller enters the device critical section.
166	*/
167	typedef DECLCALLBACK(int) FNIOMIOPORTIN(PPDMDEVINS pDevIns, void pvUser, RTIOPORT uPort, uint32_t pu32, unsigned cb);
168	/** Pointer to a FNIOMIOPORTIN(). */
169	typedef FNIOMIOPORTIN *PFNIOMIOPORTIN;
170
171	/**
172	* Port I/O Handler for string IN operations.
173	*
174	* @returns VINF_SUCCESS or VINF_EM_*.
175	* @returns VERR_IOM_IOPORT_UNUSED if the port is really unused and a ~0 value should be returned.
176	*
177	* @param pDevIns The device instance.
178	* @param pvUser User argument.
179	* @param uPort Port number used for the IN operation.
180	* @param pbDst Pointer to the destination buffer.
181	* @param pcTransfers Pointer to the number of transfer units to read, on
182	* return remaining transfer units.
183	* @param cb Size of the transfer unit (1, 2 or 4 bytes).
184	* @remarks Caller enters the device critical section.
185	*/
186	typedef DECLCALLBACK(int) FNIOMIOPORTINSTRING(PPDMDEVINS pDevIns, void pvUser, RTIOPORT uPort, uint8_t pbDst,
187	uint32_t *pcTransfers, unsigned cb);
188	/** Pointer to a FNIOMIOPORTINSTRING(). */
189	typedef FNIOMIOPORTINSTRING *PFNIOMIOPORTINSTRING;
190
191	/**
192	* Port I/O Handler for OUT operations.
193	*
194	* @returns VINF_SUCCESS or VINF_EM_*.
195	*
196	* @param pDevIns The device instance.
197	* @param pvUser User argument.
198	* @param uPort Port number used for the OUT operation.
199	* @param u32 The value to output.
200	* @param cb The value size in bytes.
201	* @remarks Caller enters the device critical section.
202	*/
203	typedef DECLCALLBACK(int) FNIOMIOPORTOUT(PPDMDEVINS pDevIns, void *pvUser, RTIOPORT uPort, uint32_t u32, unsigned cb);
204	/** Pointer to a FNIOMIOPORTOUT(). */
205	typedef FNIOMIOPORTOUT *PFNIOMIOPORTOUT;
206
207	/**
208	* Port I/O Handler for string OUT operations.
209	*
210	* @returns VINF_SUCCESS or VINF_EM_*.
211	*
212	* @param pDevIns The device instance.
213	* @param pvUser User argument.
214	* @param uPort Port number used for the OUT operation.
215	* @param pbSrc Pointer to the source buffer.
216	* @param pcTransfers Pointer to the number of transfer units to write, on
217	* return remaining transfer units.
218	* @param cb Size of the transfer unit (1, 2 or 4 bytes).
219	* @remarks Caller enters the device critical section.
220	*/
221	typedef DECLCALLBACK(int) FNIOMIOPORTOUTSTRING(PPDMDEVINS pDevIns, void pvUser, RTIOPORT uPort, const uint8_t pbSrc,
222	uint32_t *pcTransfers, unsigned cb);
223	/** Pointer to a FNIOMIOPORTOUTSTRING(). */
224	typedef FNIOMIOPORTOUTSTRING *PFNIOMIOPORTOUTSTRING;
225
226
227	/**
228	* Memory mapped I/O Handler for read operations.
229	*
230	* @returns VBox status code.
231	*
232	* @param pDevIns The device instance.
233	* @param pvUser User argument.
234	* @param GCPhysAddr Physical address (in GC) where the read starts.
235	* @param pv Where to store the result.
236	* @param cb Number of bytes read.
237	* @remarks Caller enters the device critical section.
238	*/
239	typedef DECLCALLBACK(int) FNIOMMMIOREAD(PPDMDEVINS pDevIns, void pvUser, RTGCPHYS GCPhysAddr, void pv, unsigned cb);
240	/** Pointer to a FNIOMMMIOREAD(). */
241	typedef FNIOMMMIOREAD *PFNIOMMMIOREAD;
242
243	/**
244	* Memory mapped I/O Handler for write operations.
245	*
246	* @returns VBox status code.
247	*
248	* @param pDevIns The device instance.
249	* @param pvUser User argument.
250	* @param GCPhysAddr Physical address (in GC) where the read starts.
251	* @param pv Where to fetch the result.
252	* @param cb Number of bytes to write.
253	* @remarks Caller enters the device critical section.
254	*/
255	typedef DECLCALLBACK(int) FNIOMMMIOWRITE(PPDMDEVINS pDevIns, void pvUser, RTGCPHYS GCPhysAddr, void const pv, unsigned cb);
256	/** Pointer to a FNIOMMMIOWRITE(). */
257	typedef FNIOMMMIOWRITE *PFNIOMMMIOWRITE;
258
259	/**
260	* Memory mapped I/O Handler for memset operations, actually for REP STOS* instructions handling.
261	*
262	* @returns VBox status code.
263	*
264	* @param pDevIns The device instance.
265	* @param pvUser User argument.
266	* @param GCPhysAddr Physical address (in GC) where the write starts.
267	* @param u32Item Byte/Word/Dword data to fill.
268	* @param cbItem Size of data in u32Item parameter, restricted to 1/2/4 bytes.
269	* @param cItems Number of iterations.
270	* @remarks Caller enters the device critical section.
271	*/
272	typedef DECLCALLBACK(int) FNIOMMMIOFILL(PPDMDEVINS pDevIns, void *pvUser, RTGCPHYS GCPhysAddr, uint32_t u32Item, unsigned cbItem, unsigned cItems);
273	/** Pointer to a FNIOMMMIOFILL(). */
274	typedef FNIOMMMIOFILL *PFNIOMMMIOFILL;
275
276	VMMDECL(VBOXSTRICTRC) IOMIOPortRead(PVM pVM, PVMCPU pVCpu, RTIOPORT Port, uint32_t *pu32Value, size_t cbValue);
277	VMMDECL(VBOXSTRICTRC) IOMIOPortWrite(PVM pVM, PVMCPU pVCpu, RTIOPORT Port, uint32_t u32Value, size_t cbValue);
278	VMM_INT_DECL(VBOXSTRICTRC) IOMIOPortReadString(PVM pVM, PVMCPU pVCpu, RTIOPORT Port, void *pvDst,
279	uint32_t *pcTransfers, unsigned cb);
280	VMM_INT_DECL(VBOXSTRICTRC) IOMIOPortWriteString(PVM pVM, PVMCPU pVCpu, RTIOPORT uPort, void const *pvSrc,
281	uint32_t *pcTransfers, unsigned cb);
282	VMMDECL(VBOXSTRICTRC) IOMInterpretINSEx(PVM pVM, PVMCPU pVCpu, PCPUMCTXCORE pRegFrame, uint32_t uPort, uint32_t uPrefix, DISCPUMODE enmAddrMode, uint32_t cbTransfer);
283	VMMDECL(VBOXSTRICTRC) IOMInterpretOUTSEx(PVM pVM, PVMCPU pVCpu, PCPUMCTXCORE pRegFrame, uint32_t uPort, uint32_t uPrefix, DISCPUMODE enmAddrMode, uint32_t cbTransfer);
284	VMMDECL(VBOXSTRICTRC) IOMMMIORead(PVM pVM, PVMCPU pVCpu, RTGCPHYS GCPhys, uint32_t *pu32Value, size_t cbValue);
285	VMMDECL(VBOXSTRICTRC) IOMMMIOWrite(PVM pVM, PVMCPU pVCpu, RTGCPHYS GCPhys, uint32_t u32Value, size_t cbValue);
286	VMMDECL(VBOXSTRICTRC) IOMMMIOPhysHandler(PVM pVM, PVMCPU pVCpu, RTGCUINT uErrorCode, PCPUMCTXCORE pCtxCore, RTGCPHYS GCPhysFault);
287	VMMDECL(VBOXSTRICTRC) IOMInterpretCheckPortIOAccess(PVM pVM, PCPUMCTXCORE pCtxCore, RTIOPORT Port, unsigned cb);
288	VMMDECL(int) IOMMMIOMapMMIO2Page(PVM pVM, RTGCPHYS GCPhys, RTGCPHYS GCPhysRemapped, uint64_t fPageFlags);
289	VMMDECL(int) IOMMMIOMapMMIOHCPage(PVM pVM, PVMCPU pVCpu, RTGCPHYS GCPhys, RTHCPHYS HCPhys, uint64_t fPageFlags);
290	VMMDECL(int) IOMMMIOResetRegion(PVM pVM, RTGCPHYS GCPhys);
291	VMMDECL(bool) IOMIsLockWriteOwner(PVM pVM);
292
293	#ifdef IN_RC
294	/** @defgroup grp_iom_rc The IOM Raw-Mode Context API
295	* @{
296	*/
297	VMMRCDECL(VBOXSTRICTRC) IOMRCIOPortHandler(PVM pVM, PVMCPU pVCpu, PCPUMCTXCORE pRegFrame, PDISCPUSTATE pCpu);
298	/** @} */
299	#endif /* IN_RC */
300
301
302
303	#ifdef IN_RING3
304	/** @defgroup grp_iom_r3 The IOM Host Context Ring-3 API
305	* @{
306	*/
307	VMMR3_INT_DECL(int) IOMR3Init(PVM pVM);
308	VMMR3_INT_DECL(void) IOMR3Reset(PVM pVM);
309	VMMR3_INT_DECL(void) IOMR3Relocate(PVM pVM, RTGCINTPTR offDelta);
310	VMMR3_INT_DECL(int) IOMR3Term(PVM pVM);
311	VMMR3_INT_DECL(int) IOMR3IOPortRegisterR3(PVM pVM, PPDMDEVINS pDevIns, RTIOPORT PortStart, RTUINT cPorts, RTHCPTR pvUser,
312	R3PTRTYPE(PFNIOMIOPORTOUT) pfnOutCallback, R3PTRTYPE(PFNIOMIOPORTIN) pfnInCallback,
313	R3PTRTYPE(PFNIOMIOPORTOUTSTRING) pfnOutStringCallback, R3PTRTYPE(PFNIOMIOPORTINSTRING) pfnInStringCallback,
314	const char *pszDesc);
315	VMMR3_INT_DECL(int) IOMR3IOPortRegisterRC(PVM pVM, PPDMDEVINS pDevIns, RTIOPORT PortStart, RTUINT cPorts, RTRCPTR pvUser,
316	RCPTRTYPE(PFNIOMIOPORTOUT) pfnOutCallback, RCPTRTYPE(PFNIOMIOPORTIN) pfnInCallback,
317	RCPTRTYPE(PFNIOMIOPORTOUTSTRING) pfnOutStrCallback, RCPTRTYPE(PFNIOMIOPORTINSTRING) pfnInStrCallback,
318	const char *pszDesc);
319	VMMR3_INT_DECL(int) IOMR3IOPortRegisterR0(PVM pVM, PPDMDEVINS pDevIns, RTIOPORT PortStart, RTUINT cPorts, RTR0PTR pvUser,
320	R0PTRTYPE(PFNIOMIOPORTOUT) pfnOutCallback, R0PTRTYPE(PFNIOMIOPORTIN) pfnInCallback,
321	R0PTRTYPE(PFNIOMIOPORTOUTSTRING) pfnOutStrCallback, R0PTRTYPE(PFNIOMIOPORTINSTRING) pfnInStrCallback,
322	const char *pszDesc);
323	VMMR3_INT_DECL(int) IOMR3IOPortDeregister(PVM pVM, PPDMDEVINS pDevIns, RTIOPORT PortStart, RTUINT cPorts);
324
325	VMMR3_INT_DECL(int) IOMR3MmioRegisterR3(PVM pVM, PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange, RTHCPTR pvUser,
326	R3PTRTYPE(PFNIOMMMIOWRITE) pfnWriteCallback,
327	R3PTRTYPE(PFNIOMMMIOREAD) pfnReadCallback,
328	R3PTRTYPE(PFNIOMMMIOFILL) pfnFillCallback,
329	uint32_t fFlags, const char *pszDesc);
330	VMMR3_INT_DECL(int) IOMR3MmioRegisterR0(PVM pVM, PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange, RTR0PTR pvUser,
331	R0PTRTYPE(PFNIOMMMIOWRITE) pfnWriteCallback,
332	R0PTRTYPE(PFNIOMMMIOREAD) pfnReadCallback,
333	R0PTRTYPE(PFNIOMMMIOFILL) pfnFillCallback);
334	VMMR3_INT_DECL(int) IOMR3MmioRegisterRC(PVM pVM, PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange, RTGCPTR pvUser,
335	RCPTRTYPE(PFNIOMMMIOWRITE) pfnWriteCallback,
336	RCPTRTYPE(PFNIOMMMIOREAD) pfnReadCallback,
337	RCPTRTYPE(PFNIOMMMIOFILL) pfnFillCallback);
338	VMMR3_INT_DECL(int) IOMR3MmioDeregister(PVM pVM, PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange);
339
340	/** @} */
341	#endif /* IN_RING3 */
342
343
344	/** @} */
345
346	RT_C_DECLS_END
347
348	#endif
349

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/include/VBox/vmm/iom.h@ 58650

Download in other formats: