iom.h@ 7581

Last change on this file since 7581 was 7133, checked in by vboxsync, 17 years ago
Eliminate cpum.h dependency (shuts up a bunch of .c warnings). Fixed the header tests.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 32.3 KB

Line
1	/** @file
2	* IOM - Input / Output Monitor.
3	*/
4
5	/*
6	* Copyright (C) 2006-2007 innotek GmbH
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_iom_h
27	#define ___VBox_iom_h
28
29	#include <VBox/cdefs.h>
30	#include <VBox/types.h>
31	#include <VBox/dis.h>
32
33	__BEGIN_DECLS
34
35
36	/** @defgroup grp_iom The Input / Ouput Monitor API
37	* @{
38	*/
39
40	/** @def IOM_NO_PDMINS_CHECKS
41	* Untill all devices have been fully adjusted to PDM style, the pPdmIns parameter
42	* is not checked by IOM.
43	*/
44	#define IOM_NO_PDMINS_CHECKS
45
46	/**
47	* Macro for checking if an I/O or MMIO emulation call succeeded.
48	*
49	* This macro shall only be used with the IOM APIs where it's mentioned
50	* in the return value description. And there is must be used to correctly
51	* determin if the call succeeded and things like the EIP needs updating.
52	*
53	*
54	* @returns Success indicator (true/false).
55	*
56	* @param rc The status code. This may be evaluated
57	* more than once!
58	*
59	* @remark To avoid making assumptions about the layout of the
60	* VINF_EM_FIRST...VINF_EM_LAST range we're checking
61	* explicitly for each for exach the exceptions.
62	* However, for efficieny we ASSUME that the
63	* VINF_EM_LAST is smaller than most of the relevant
64	* status codes. We also ASSUME that the
65	* VINF_EM_RESCHEDULE_REM status code is the most
66	* frequent status code we'll enounter in this range.
67	*
68	* @todo Will have to add VINF_EM_DBG_HYPER_BREAKPOINT if the
69	* I/O port and MMIO breakpoints should trigger before
70	* the I/O is done. Currently, we don't implement these
71	* kind of breakpoints.
72	*/
73	#define IOM_SUCCESS(rc) ( (rc) == VINF_SUCCESS \
74	\|\| ( (rc) <= VINF_EM_LAST \
75	&& (rc) != VINF_EM_RESCHEDULE_REM \
76	&& (rc) >= VINF_EM_FIRST \
77	&& (rc) != VINF_EM_RESCHEDULE_RAW \
78	&& (rc) != VINF_EM_RESCHEDULE_HWACC \
79	) \
80	)
81
82
83	/**
84	* Port I/O Handler for IN operations.
85	*
86	* @returns VINF_SUCCESS or VINF_EM_*.
87	* @returns VERR_IOM_IOPORT_UNUSED if the port is really unused and a ~0 value should be returned.
88	*
89	* @param pDevIns The device instance.
90	* @param pvUser User argument.
91	* @param uPort Port number used for the IN operation.
92	* @param pu32 Where to store the result.
93	* @param cb Number of bytes read.
94	*/
95	typedef DECLCALLBACK(int) FNIOMIOPORTIN(PPDMDEVINS pDevIns, void pvUser, RTIOPORT Port, uint32_t pu32, unsigned cb);
96	/** Pointer to a FNIOMIOPORTIN(). */
97	typedef FNIOMIOPORTIN *PFNIOMIOPORTIN;
98
99	/**
100	* Port I/O Handler for string IN operations.
101	*
102	* @returns VINF_SUCCESS or VINF_EM_*.
103	* @returns VERR_IOM_IOPORT_UNUSED if the port is really unused and a ~0 value should be returned.
104	*
105	* @param pDevIns The device instance.
106	* @param pvUser User argument.
107	* @param uPort Port number used for the IN operation.
108	* @param pGCPtrDst Pointer to the destination buffer (GC, incremented appropriately).
109	* @param pcTransfers Pointer to the number of transfer units to read, on return remaining transfer units.
110	* @param cb Size of the transfer unit (1, 2 or 4 bytes).
111	*/
112	typedef DECLCALLBACK(int) FNIOMIOPORTINSTRING(PPDMDEVINS pDevIns, void pvUser, RTIOPORT Port, RTGCPTR pGCPtrDst, unsigned *pcTransfers, unsigned cb);
113	/** Pointer to a FNIOMIOPORTINSTRING(). */
114	typedef FNIOMIOPORTINSTRING *PFNIOMIOPORTINSTRING;
115
116	/**
117	* Port I/O Handler for OUT operations.
118	*
119	* @returns VINF_SUCCESS or VINF_EM_*.
120	*
121	* @param pDevIns The device instance.
122	* @param pvUser User argument.
123	* @param uPort Port number used for the OUT operation.
124	* @param u32 The value to output.
125	* @param cb The value size in bytes.
126	*/
127	typedef DECLCALLBACK(int) FNIOMIOPORTOUT(PPDMDEVINS pDevIns, void *pvUser, RTIOPORT Port, uint32_t u32, unsigned cb);
128	/** Pointer to a FNIOMIOPORTOUT(). */
129	typedef FNIOMIOPORTOUT *PFNIOMIOPORTOUT;
130
131	/**
132	* Port I/O Handler for string OUT operations.
133	*
134	* @returns VINF_SUCCESS or VINF_EM_*.
135	*
136	* @param pDevIns The device instance.
137	* @param pvUser User argument.
138	* @param uPort Port number used for the OUT operation.
139	* @param pGCPtrSrc Pointer to the source buffer (GC, incremented appropriately).
140	* @param pcTransfers Pointer to the number of transfer units to write, on return remaining transfer units.
141	* @param cb Size of the transfer unit (1, 2 or 4 bytes).
142	*/
143	typedef DECLCALLBACK(int) FNIOMIOPORTOUTSTRING(PPDMDEVINS pDevIns, void pvUser, RTIOPORT Port, RTGCPTR pGCPtrSrc, unsigned *pcTransfers, unsigned cb);
144	/** Pointer to a FNIOMIOPORTOUTSTRING(). */
145	typedef FNIOMIOPORTOUTSTRING *PFNIOMIOPORTOUTSTRING;
146
147
148	/**
149	* Memory mapped I/O Handler for read operations.
150	*
151	* @returns VBox status code.
152	*
153	* @param pDevIns The device instance.
154	* @param pvUser User argument.
155	* @param GCPhysAddr Physical address (in GC) where the read starts.
156	* @param pv Where to store the result.
157	* @param cb Number of bytes read.
158	*
159	* @remark wonder if we could merge the IOMMMIO* and IOMPORT* callbacks...
160	*/
161	typedef DECLCALLBACK(int) FNIOMMMIOREAD(PPDMDEVINS pDevIns, void pvUser, RTGCPHYS GCPhysAddr, void pv, unsigned cb);
162	/** Pointer to a FNIOMMMIOREAD(). */
163	typedef FNIOMMMIOREAD *PFNIOMMMIOREAD;
164
165	/**
166	* Port I/O Handler for write operations.
167	*
168	* @returns VBox status code.
169	*
170	* @param pDevIns The device instance.
171	* @param pvUser User argument.
172	* @param GCPhysAddr Physical address (in GC) where the read starts.
173	* @param pv Where to fetch the result.
174	* @param cb Number of bytes to write.
175	*
176	* @remark wonder if we could merge the IOMMMIO* and IOMPORT* callbacks...
177	*/
178	typedef DECLCALLBACK(int) FNIOMMMIOWRITE(PPDMDEVINS pDevIns, void pvUser, RTGCPHYS GCPhysAddr, void pv, unsigned cb);
179	/** Pointer to a FNIOMMMIOWRITE(). */
180	typedef FNIOMMMIOWRITE *PFNIOMMMIOWRITE;
181
182	/**
183	* Port I/O Handler for memset operations, actually for REP STOS* instructions handling.
184	*
185	* @returns VBox status code.
186	*
187	* @param pDevIns The device instance.
188	* @param pvUser User argument.
189	* @param GCPhysAddr Physical address (in GC) where the write starts.
190	* @param u32Item Byte/Word/Dword data to fill.
191	* @param cbItem Size of data in u32Item parameter, restricted to 1/2/4 bytes.
192	* @param cItems Number of iterations.
193	*/
194	typedef DECLCALLBACK(int) FNIOMMMIOFILL(PPDMDEVINS pDevIns, void *pvUser, RTGCPHYS GCPhysAddr, uint32_t u32Item, unsigned cbItem, unsigned cItems);
195	/** Pointer to a FNIOMMMIOFILL(). */
196	typedef FNIOMMMIOFILL *PFNIOMMMIOFILL;
197
198
199
200	/**
201	* Registers a Port IO GC handler.
202	*
203	* This API is called by PDM on behalf of a device. Devices must first register HC ranges
204	* using IOMR3IOPortRegisterHC() before calling this function.
205	*
206	*
207	* @returns VBox status code.
208	*
209	* @param pVM VM handle.
210	* @param pDevIns PDM device instance owning the port range.
211	* @param PortStart First port number in the range.
212	* @param cPorts Number of ports to register.
213	* @param pvUser User argument for the callbacks.
214	* @param pfnOutCallback Pointer to function which is gonna handle OUT operations in GC.
215	* @param pfnInCallback Pointer to function which is gonna handle IN operations in GC.
216	* @param pfnOutStrCallback Pointer to function which is gonna handle OUT operations in GC.
217	* @param pfnInStrCallback Pointer to function which is gonna handle IN operations in GC.
218	* @param pszDesc Pointer to description string. This must not be freed.
219	*/
220	IOMDECL(int) IOMIOPortRegisterGC(PVM pVM, PPDMDEVINS pDevIns, RTIOPORT PortStart, RTUINT cPorts, RTGCPTR pvUser,
221	GCPTRTYPE(PFNIOMIOPORTOUT) pfnOutCallback, GCPTRTYPE(PFNIOMIOPORTIN) pfnInCallback,
222	GCPTRTYPE(PFNIOMIOPORTOUTSTRING) pfnOutStrCallback, GCPTRTYPE(PFNIOMIOPORTINSTRING) pfnInStrCallback,
223	const char *pszDesc);
224
225
226
227	/**
228	* Registers a Memory Mapped I/O GC handler range.
229	*
230	* This API is called by PDM on behalf of a device. Devices must first register HC ranges
231	* using IOMMR3MIORegisterHC() before calling this function.
232	*
233	*
234	* @returns VBox status code.
235	*
236	* @param pVM VM handle.
237	* @param pDevIns PDM device instance owning the MMIO range.
238	* @param GCPhysStart First physical address in the range.
239	* @param cbRange The size of the range (in bytes).
240	* @param pvUser User argument for the callbacks.
241	* @param pfnWriteCallback Pointer to function which is gonna handle Write operations.
242	* @param pfnReadCallback Pointer to function which is gonna handle Read operations.
243	* @param pfnFillCallback Pointer to function which is gonna handle Fill/memset operations.
244	* @param pszDesc Pointer to description string. This must not be freed.
245	*/
246	IOMDECL(int) IOMMMIORegisterGC(PVM pVM, PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, RTGCPTR pvUser,
247	GCPTRTYPE(PFNIOMMMIOWRITE) pfnWriteCallback, GCPTRTYPE(PFNIOMMMIOREAD) pfnReadCallback,
248	GCPTRTYPE(PFNIOMMMIOFILL) pfnFillCallback, const char *pszDesc);
249
250
251	/**
252	* Registers a Port IO R0 handler.
253	*
254	* This API is called by PDM on behalf of a device. Devices must first register ring-3 ranges
255	* using IOMR3IOPortRegisterR3() before calling this function.
256	*
257	*
258	* @returns VBox status code.
259	*
260	* @param pVM VM handle.
261	* @param pDevIns PDM device instance owning the port range.
262	* @param PortStart First port number in the range.
263	* @param cPorts Number of ports to register.
264	* @param pvUser User argument for the callbacks.
265	* @param pfnOutCallback Pointer to function which is gonna handle OUT operations in GC.
266	* @param pfnInCallback Pointer to function which is gonna handle IN operations in GC.
267	* @param pfnOutStrCallback Pointer to function which is gonna handle OUT operations in GC.
268	* @param pfnInStrCallback Pointer to function which is gonna handle IN operations in GC.
269	* @param pszDesc Pointer to description string. This must not be freed.
270	*/
271	IOMDECL(int) IOMIOPortRegisterR0(PVM pVM, PPDMDEVINS pDevIns, RTIOPORT PortStart, RTUINT cPorts, RTR0PTR pvUser,
272	R0PTRTYPE(PFNIOMIOPORTOUT) pfnOutCallback, R0PTRTYPE(PFNIOMIOPORTIN) pfnInCallback,
273	R0PTRTYPE(PFNIOMIOPORTOUTSTRING) pfnOutStrCallback, R0PTRTYPE(PFNIOMIOPORTINSTRING) pfnInStrCallback,
274	const char *pszDesc);
275
276	/**
277	* Registers a Memory Mapped I/O R0 handler range.
278	*
279	* This API is called by PDM on behalf of a device. Devices must first register ring-3 ranges
280	* using IOMMR3MIORegisterR3() before calling this function.
281	*
282	*
283	* @returns VBox status code.
284	*
285	* @param pVM VM handle.
286	* @param pDevIns PDM device instance owning the MMIO range.
287	* @param GCPhysStart First physical address in the range.
288	* @param cbRange The size of the range (in bytes).
289	* @param pvUser User argument for the callbacks.
290	* @param pfnWriteCallback Pointer to function which is gonna handle Write operations.
291	* @param pfnReadCallback Pointer to function which is gonna handle Read operations.
292	* @param pfnFillCallback Pointer to function which is gonna handle Fill/memset operations.
293	* @param pszDesc Pointer to description string. This must not be freed.
294	*/
295	IOMDECL(int) IOMMMIORegisterR0(PVM pVM, PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, RTR0PTR pvUser,
296	R0PTRTYPE(PFNIOMMMIOWRITE) pfnWriteCallback, R0PTRTYPE(PFNIOMMMIOREAD) pfnReadCallback,
297	R0PTRTYPE(PFNIOMMMIOFILL) pfnFillCallback, const char *pszDesc);
298
299
300	/**
301	* Reads an I/O port register.
302	*
303	* @returns Strict VBox status code. Informational status codes other than the one documented
304	* here are to be treated as internal failure. Use IOM_SUCCESS() to check for success.
305	* @retval VINF_SUCCESS Success.
306	* @retval VINF_EM_FIRST-VINF_EM_LAST Success with some exceptions (see IOM_SUCCESS()), the
307	* status code must be passed on to EM.
308	* @retval VINF_IOM_HC_IOPORT_READ Defer the read to ring-3. (R0/GC only)
309	*
310	* @param pVM VM handle.
311	* @param Port The port to read.
312	* @param pu32Value Where to store the value read.
313	* @param cbValue The size of the register to read in bytes. 1, 2 or 4 bytes.
314	*/
315	IOMDECL(int) IOMIOPortRead(PVM pVM, RTIOPORT Port, uint32_t *pu32Value, size_t cbValue);
316
317	/**
318	* Writes to an I/O port register.
319	*
320	* @returns Strict VBox status code. Informational status codes other than the one documented
321	* here are to be treated as internal failure. Use IOM_SUCCESS() to check for success.
322	* @retval VINF_SUCCESS Success.
323	* @retval VINF_EM_FIRST-VINF_EM_LAST Success with some exceptions (see IOM_SUCCESS()), the
324	* status code must be passed on to EM.
325	* @retval VINF_IOM_HC_IOPORT_WRITE Defer the write to ring-3. (R0/GC only)
326	*
327	* @param pVM VM handle.
328	* @param Port The port to write to.
329	* @param u32Value The value to write.
330	* @param cbValue The size of the register to read in bytes. 1, 2 or 4 bytes.
331	*/
332	IOMDECL(int) IOMIOPortWrite(PVM pVM, RTIOPORT Port, uint32_t u32Value, size_t cbValue);
333
334	/**
335	* OUT <DX\|imm16>, <AL\|AX\|EAX>
336	*
337	* @returns Strict VBox status code. Informational status codes other than the one documented
338	* here are to be treated as internal failure. Use IOM_SUCCESS() to check for success.
339	* @retval VINF_SUCCESS Success.
340	* @retval VINF_EM_FIRST-VINF_EM_LAST Success with some exceptions (see IOM_SUCCESS()), the
341	* status code must be passed on to EM.
342	* @retval VINF_IOM_HC_IOPORT_WRITE Defer the write to ring-3. (R0/GC only)
343	* @retval VINF_EM_RAW_GUEST_TRAP The exception was left pending. (TRPMRaiseXcptErr)
344	* @retval VINF_TRPM_XCPT_DISPATCHED The exception was raised and dispatched for raw-mode execution. (TRPMRaiseXcptErr)
345	* @retval VINF_EM_RESCHEDULE_REM The exception was dispatched and cannot be executed in raw-mode. (TRPMRaiseXcptErr)
346	*
347	* @param pVM The virtual machine (GC pointer ofcourse).
348	* @param pRegFrame Pointer to CPUMCTXCORE guest registers structure.
349	* @param pCpu Disassembler CPU state.
350	*/
351	IOMDECL(int) IOMInterpretOUT(PVM pVM, PCPUMCTXCORE pRegFrame, PDISCPUSTATE pCpu);
352
353	/**
354	* IN <AL\|AX\|EAX>, <DX\|imm16>
355	*
356	* @returns Strict VBox status code. Informational status codes other than the one documented
357	* here are to be treated as internal failure. Use IOM_SUCCESS() to check for success.
358	* @retval VINF_SUCCESS Success.
359	* @retval VINF_EM_FIRST-VINF_EM_LAST Success with some exceptions (see IOM_SUCCESS()), the
360	* status code must be passed on to EM.
361	* @retval VINF_IOM_HC_IOPORT_READ Defer the read to ring-3. (R0/GC only)
362	* @retval VINF_EM_RAW_GUEST_TRAP The exception was left pending. (TRPMRaiseXcptErr)
363	* @retval VINF_TRPM_XCPT_DISPATCHED The exception was raised and dispatched for raw-mode execution. (TRPMRaiseXcptErr)
364	* @retval VINF_EM_RESCHEDULE_REM The exception was dispatched and cannot be executed in raw-mode. (TRPMRaiseXcptErr)
365	*
366	* @param pVM The virtual machine (GC pointer ofcourse).
367	* @param pRegFrame Pointer to CPUMCTXCORE guest registers structure.
368	* @param pCpu Disassembler CPU state.
369	*/
370	IOMDECL(int) IOMInterpretIN(PVM pVM, PCPUMCTXCORE pRegFrame, PDISCPUSTATE pCpu);
371
372
373	/**
374	* Reads the string buffer of an I/O port register.
375	*
376	* @returns Strict VBox status code. Informational status codes other than the one documented
377	* here are to be treated as internal failure. Use IOM_SUCCESS() to check for success.
378	* @retval VINF_SUCCESS Success.
379	* @retval VINF_EM_FIRST-VINF_EM_LAST Success with some exceptions (see IOM_SUCCESS()), the
380	* status code must be passed on to EM.
381	* @retval VINF_IOM_HC_IOPORT_READ Defer the read to ring-3. (R0/GC only)
382	*
383	* @param pVM VM handle.
384	* @param Port The port to read.
385	* @param pGCPtrDst Pointer to the destination buffer (GC, incremented appropriately).
386	* @param pcTransfers Pointer to the number of transfer units to read, on return remaining transfer units.
387	* @param cb Size of the transfer unit (1, 2 or 4 bytes).
388	*/
389	IOMDECL(int) IOMIOPortReadString(PVM pVM, RTIOPORT Port, PRTGCPTR pGCPtrDst, PRTGCUINTREG pcTransfers, unsigned cb);
390
391	/**
392	* Writes the string buffer of an I/O port register.
393	*
394	* @returns Strict VBox status code. Informational status codes other than the one documented
395	* here are to be treated as internal failure.
396	* @retval VINF_SUCCESS Success.
397	* @retval VINF_EM_FIRST-VINF_EM_LAST Success but schedulinging information needs to be passed onto EM.
398	* @retval VINF_IOM_HC_IOPORT_WRITE Defer the write to ring-3. (R0/GC only)
399	*
400	* @param pVM VM handle.
401	* @param Port The port to write.
402	* @param pGCPtrSrc Pointer to the source buffer (GC, incremented appropriately).
403	* @param pcTransfer Pointer to the number of transfer units to write, on return remaining transfer units.
404	* @param cb Size of the transfer unit (1, 2 or 4 bytes).
405	*/
406	IOMDECL(int) IOMIOPortWriteString(PVM pVM, RTIOPORT Port, PRTGCPTR pGCPtrSrc, PRTGCUINTREG pcTransfers, unsigned cb);
407
408	/**
409	* [REP*] INSB/INSW/INSD
410	* ES:EDI,DX[,ECX]
411	*
412	* @returns Strict VBox status code. Informational status codes other than the one documented
413	* here are to be treated as internal failure. Use IOM_SUCCESS() to check for success.
414	* @retval VINF_SUCCESS Success.
415	* @retval VINF_EM_FIRST-VINF_EM_LAST Success with some exceptions (see IOM_SUCCESS()), the
416	* status code must be passed on to EM.
417	* @retval VINF_IOM_HC_IOPORT_READ Defer the read to ring-3. (R0/GC only)
418	* @retval VINF_EM_RAW_EMULATE_INSTR Defer the read to the REM.
419	* @retval VINF_EM_RAW_GUEST_TRAP The exception was left pending. (TRPMRaiseXcptErr)
420	* @retval VINF_TRPM_XCPT_DISPATCHED The exception was raised and dispatched for raw-mode execution. (TRPMRaiseXcptErr)
421	* @retval VINF_EM_RESCHEDULE_REM The exception was dispatched and cannot be executed in raw-mode. (TRPMRaiseXcptErr)
422	*
423	* @param pVM The virtual machine (GC pointer ofcourse).
424	* @param pRegFrame Pointer to CPUMCTXCORE guest registers structure.
425	* @param pCpu Disassembler CPU state.
426	*/
427	IOMDECL(int) IOMInterpretINS(PVM pVM, PCPUMCTXCORE pRegFrame, PDISCPUSTATE pCpu);
428
429	/**
430	* [REP*] INSB/INSW/INSD
431	* ES:EDI,DX[,ECX]
432	*
433	* @remark Assumes caller checked the access privileges (IOMInterpretCheckPortIOAccess)
434	*
435	* @returns Strict VBox status code. Informational status codes other than the one documented
436	* here are to be treated as internal failure. Use IOM_SUCCESS() to check for success.
437	* @retval VINF_SUCCESS Success.
438	* @retval VINF_EM_FIRST-VINF_EM_LAST Success with some exceptions (see IOM_SUCCESS()), the
439	* status code must be passed on to EM.
440	* @retval VINF_IOM_HC_IOPORT_READ Defer the read to ring-3. (R0/GC only)
441	* @retval VINF_EM_RAW_EMULATE_INSTR Defer the read to the REM.
442	* @retval VINF_EM_RAW_GUEST_TRAP The exception was left pending. (TRPMRaiseXcptErr)
443	* @retval VINF_TRPM_XCPT_DISPATCHED The exception was raised and dispatched for raw-mode execution. (TRPMRaiseXcptErr)
444	* @retval VINF_EM_RESCHEDULE_REM The exception was dispatched and cannot be executed in raw-mode. (TRPMRaiseXcptErr)
445	*
446	* @param pVM The virtual machine (GC pointer ofcourse).
447	* @param pRegFrame Pointer to CPUMCTXCORE guest registers structure.
448	* @param uPort IO Port
449	* @param uPrefix IO instruction prefix
450	* @param cbTransfer Size of transfer unit
451	*/
452	IOMDECL(int) IOMInterpretINSEx(PVM pVM, PCPUMCTXCORE pRegFrame, uint32_t uPort, uint32_t uPrefix, uint32_t cbTransfer);
453
454	/**
455	* [REP*] OUTSB/OUTSW/OUTSD
456	* DS:ESI,DX[,ECX]
457	*
458	* @returns Strict VBox status code. Informational status codes other than the one documented
459	* here are to be treated as internal failure. Use IOM_SUCCESS() to check for success.
460	* @retval VINF_SUCCESS Success.
461	* @retval VINF_EM_FIRST-VINF_EM_LAST Success with some exceptions (see IOM_SUCCESS()), the
462	* status code must be passed on to EM.
463	* @retval VINF_IOM_HC_IOPORT_WRITE Defer the write to ring-3. (R0/GC only)
464	* @retval VINF_EM_RAW_EMULATE_INSTR Defer the write to the REM.
465	* @retval VINF_EM_RAW_GUEST_TRAP The exception was left pending. (TRPMRaiseXcptErr)
466	* @retval VINF_TRPM_XCPT_DISPATCHED The exception was raised and dispatched for raw-mode execution. (TRPMRaiseXcptErr)
467	* @retval VINF_EM_RESCHEDULE_REM The exception was dispatched and cannot be executed in raw-mode. (TRPMRaiseXcptErr)
468	*
469	* @param pVM The virtual machine (GC pointer ofcourse).
470	* @param pRegFrame Pointer to CPUMCTXCORE guest registers structure.
471	* @param pCpu Disassembler CPU state.
472	*/
473	IOMDECL(int) IOMInterpretOUTS(PVM pVM, PCPUMCTXCORE pRegFrame, PDISCPUSTATE pCpu);
474
475	/**
476	* [REP*] OUTSB/OUTSW/OUTSD
477	* DS:ESI,DX[,ECX]
478	*
479	* @remark Assumes caller checked the access privileges (IOMInterpretCheckPortIOAccess)
480	*
481	* @returns Strict VBox status code. Informational status codes other than the one documented
482	* here are to be treated as internal failure. Use IOM_SUCCESS() to check for success.
483	* @retval VINF_SUCCESS Success.
484	* @retval VINF_EM_FIRST-VINF_EM_LAST Success with some exceptions (see IOM_SUCCESS()), the
485	* status code must be passed on to EM.
486	* @retval VINF_IOM_HC_IOPORT_WRITE Defer the write to ring-3. (R0/GC only)
487	* @retval VINF_EM_RAW_EMULATE_INSTR Defer the write to the REM.
488	* @retval VINF_EM_RAW_GUEST_TRAP The exception was left pending. (TRPMRaiseXcptErr)
489	* @retval VINF_TRPM_XCPT_DISPATCHED The exception was raised and dispatched for raw-mode execution. (TRPMRaiseXcptErr)
490	* @retval VINF_EM_RESCHEDULE_REM The exception was dispatched and cannot be executed in raw-mode. (TRPMRaiseXcptErr)
491	*
492	* @param pVM The virtual machine (GC pointer ofcourse).
493	* @param pRegFrame Pointer to CPUMCTXCORE guest registers structure.
494	* @param uPort IO Port
495	* @param uPrefix IO instruction prefix
496	* @param cbTransfer Size of transfer unit
497	*/
498	IOMDECL(int) IOMInterpretOUTSEx(PVM pVM, PCPUMCTXCORE pRegFrame, uint32_t uPort, uint32_t uPrefix, uint32_t cbTransfer);
499
500	/**
501	* Flushes the IOM port & statistics lookup cache
502	*
503	* @param pVM The VM.
504	*/
505	IOMDECL(void) IOMFlushCache(PVM pVM);
506
507	/**
508	* Reads a MMIO register.
509	*
510	* @returns VBox status code.
511	*
512	* @param pVM VM handle.
513	* @param GCPhys The physical address to read.
514	* @param pu32Value Where to store the value read.
515	* @param cbValue The size of the register to read in bytes. 1, 2 or 4 bytes.
516	*/
517	IOMDECL(int) IOMMMIORead(PVM pVM, RTGCPHYS GCPhys, uint32_t *pu32Value, size_t cbValue);
518
519	/**
520	* Writes to a MMIO register.
521	*
522	* @returns VBox status code.
523	*
524	* @param pVM VM handle.
525	* @param GCPhys The physical address to write to.
526	* @param u32Value The value to write.
527	* @param cbValue The size of the register to read in bytes. 1, 2 or 4 bytes.
528	*/
529	IOMDECL(int) IOMMMIOWrite(PVM pVM, RTGCPHYS GCPhys, uint32_t u32Value, size_t cbValue);
530
531
532	/**
533	* Checks that the operation is allowed according to the IOPL
534	* level and I/O bitmap.
535	*
536	* @returns Strict VBox status code. Informational status codes other than the one documented
537	* here are to be treated as internal failure.
538	* @retval VINF_SUCCESS Success.
539	* @retval VINF_EM_RAW_GUEST_TRAP The exception was left pending. (TRPMRaiseXcptErr)
540	* @retval VINF_TRPM_XCPT_DISPATCHED The exception was raised and dispatched for raw-mode execution. (TRPMRaiseXcptErr)
541	* @retval VINF_EM_RESCHEDULE_REM The exception was dispatched and cannot be executed in raw-mode. (TRPMRaiseXcptErr)
542	*
543	* @param pVM VM handle.
544	* @param pCtxCore Pointer to register frame.
545	* @param Port The I/O port number.
546	* @param cb The access size.
547	*/
548	IOMDECL(int) IOMInterpretCheckPortIOAccess(PVM pVM, PCPUMCTXCORE pCtxCore, RTIOPORT Port, unsigned cb);
549
550
551	#ifdef IN_GC
552	/** @defgroup grp_iom_gc The IOM Guest Context API
553	* @ingroup grp_iom
554	* @{
555	*/
556
557	/**
558	* Attempts to service an IN/OUT instruction.
559	*
560	* The \#GP trap handler in GC will call this function if the opcode causing the
561	* trap is a in or out type instruction. (Call it indirectly via EM that is.)
562	*
563	* @returns Strict VBox status code. Informational status codes other than the one documented
564	* here are to be treated as internal failure. Use IOM_SUCCESS() to check for success.
565	* @retval VINF_SUCCESS Success.
566	* @retval VINF_EM_FIRST-VINF_EM_LAST Success with some exceptions (see IOM_SUCCESS()), the
567	* status code must be passed on to EM.
568	* @retval VINF_IOM_HC_IOPORT_READ Defer the read to ring-3. (R0/GC only)
569	* @retval VINF_EM_RAW_GUEST_TRAP The exception was left pending. (TRPMRaiseXcptErr)
570	* @retval VINF_TRPM_XCPT_DISPATCHED The exception was raised and dispatched for raw-mode execution. (TRPMRaiseXcptErr)
571	* @retval VINF_EM_RESCHEDULE_REM The exception was dispatched and cannot be executed in raw-mode. (TRPMRaiseXcptErr)
572	*
573	* @param pVM The virtual machine (GC pointer ofcourse).
574	* @param pRegFrame Pointer to CPUMCTXCORE guest registers structure.
575	* @param pCpu Disassembler CPU state.
576	*/
577	IOMGCDECL(int) IOMGCIOPortHandler(PVM pVM, PCPUMCTXCORE pRegFrame, PDISCPUSTATE pCpu);
578
579	/** @} */
580	#endif
581
582
583
584	#ifdef IN_RING3
585	/** @defgroup grp_iom_r3 The IOM Host Context Ring-3 API
586	* @ingroup grp_iom
587	* @{
588	*/
589
590	/**
591	* Initializes the IOM.
592	*
593	* @returns VBox status code.
594	* @param pVM The VM to operate on.
595	*/
596	IOMR3DECL(int) IOMR3Init(PVM pVM);
597
598	/**
599	* The VM is being reset.
600	*
601	* @param pVM VM handle.
602	*/
603	IOMR3DECL(void) IOMR3Reset(PVM pVM);
604
605	/**
606	* Applies relocations to data and code managed by this
607	* component. This function will be called at init and
608	* whenever the VMM need to relocate it self inside the GC.
609	*
610	* The IOM will update the addresses used by the switcher.
611	*
612	* @param pVM The VM.
613	* @param offDelta Relocation delta relative to old location.
614	*/
615	IOMR3DECL(void) IOMR3Relocate(PVM pVM, RTGCINTPTR offDelta);
616
617	/**
618	* Terminates the IOM.
619	*
620	* Termination means cleaning up and freeing all resources,
621	* the VM it self is at this point powered off or suspended.
622	*
623	* @returns VBox status code.
624	* @param pVM The VM to operate on.
625	*/
626	IOMR3DECL(int) IOMR3Term(PVM pVM);
627
628	/**
629	* Registers a I/O port R3 handler.
630	*
631	* This API is called by PDM on behalf of a device. Devices must first register
632	* ring-3 ranges before any GC and R0 ranges can be registered using IOMIOPortRegisterGC()
633	* and IOMIOPortRegisterR0().
634	*
635	* @returns VBox status code.
636	*
637	* @param pVM VM handle.
638	* @param pDevIns PDM device instance owning the port range.
639	* @param PortStart First port number in the range.
640	* @param cPorts Number of ports to register.
641	* @param pvUser User argument for the callbacks.
642	* @param pfnOutCallback Pointer to function which is gonna handle OUT operations in R3.
643	* @param pfnInCallback Pointer to function which is gonna handle IN operations in R3.
644	* @param pfnOutStringCallback Pointer to function which is gonna handle string OUT operations in R3.
645	* @param pfnInStringCallback Pointer to function which is gonna handle string IN operations in R3.
646	* @param pszDesc Pointer to description string. This must not be freed.
647	*/
648	IOMR3DECL(int) IOMR3IOPortRegisterR3(PVM pVM, PPDMDEVINS pDevIns, RTIOPORT PortStart, RTUINT cPorts, RTHCPTR pvUser,
649	R3PTRTYPE(PFNIOMIOPORTOUT) pfnOutCallback, R3PTRTYPE(PFNIOMIOPORTIN) pfnInCallback,
650	R3PTRTYPE(PFNIOMIOPORTOUTSTRING) pfnOutStringCallback, R3PTRTYPE(PFNIOMIOPORTINSTRING) pfnInStringCallback,
651	const char *pszDesc);
652
653	/**
654	* Registers a Memory Mapped I/O R3 handler.
655	*
656	* This API is called by PDM on behalf of a device. Devices must register ring-3 ranges
657	* before any GC and R0 ranges can be registered using IOMMMIORegisterGC() and IOMMMIORegisterR0().
658	*
659	* @returns VBox status code.
660	*
661	* @param pVM VM handle.
662	* @param pDevIns PDM device instance owning the MMIO range.
663	* @param GCPhysStart First physical address in the range.
664	* @param cbRange The size of the range (in bytes).
665	* @param pvUser User argument for the callbacks.
666	* @param pfnWriteCallback Pointer to function which is gonna handle Write operations.
667	* @param pfnReadCallback Pointer to function which is gonna handle Read operations.
668	* @param pfnFillCallback Pointer to function which is gonna handle Fill/memset operations.
669	* @param pszDesc Pointer to description string. This must not be freed.
670	*/
671	IOMR3DECL(int) IOMR3MMIORegisterR3(PVM pVM, PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, RTHCPTR pvUser,
672	R3PTRTYPE(PFNIOMMMIOWRITE) pfnWriteCallback, R3PTRTYPE(PFNIOMMMIOREAD) pfnReadCallback,
673	R3PTRTYPE(PFNIOMMMIOFILL) pfnFillCallback, const char *pszDesc);
674
675
676
677	/**
678	* Deregisters a I/O Port range.
679	*
680	* The specified range must be registered using IOMR3IOPortRegister previous to
681	* this call. The range does can be a smaller part of the range specified to
682	* IOMR3IOPortRegister, but it can never be larger.
683	*
684	* This function will remove GC, R0 and R3 context port handlers for this range.
685	*
686	* @returns VBox status code.
687	*
688	* @param pVM The virtual machine.
689	* @param pDevIns The device instance associated with the range.
690	* @param PortStart First port number in the range.
691	* @param cPorts Number of ports to remove starting at PortStart.
692	*/
693	IOMR3DECL(int) IOMR3IOPortDeregister(PVM pVM, PPDMDEVINS pDevIns, RTIOPORT PortStart, RTUINT cPorts);
694
695
696	/**
697	* Deregisters a Memory Mapped I/O handler range.
698	*
699	* Registered GC, R0, and R3 ranges are affected.
700	*
701	* @returns VBox status code.
702	*
703	* @param pVM The virtual machine.
704	* @param pDevIns Device instance which the MMIO region is registered.
705	* @param GCPhysStart First physical address (GC) in the range.
706	* @param cbRange Number of bytes to deregister.
707	*
708	*
709	* @remark This function mainly for PCI PnP Config and will not do
710	* all the checks you might expect it to do.
711	*/
712	IOMR3DECL(int) IOMR3MMIODeregister(PVM pVM, PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange);
713
714
715	/** @} */
716	#endif
717
718
719	/** @} */
720
721	__END_DECLS
722
723	#endif
724

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

source: vbox/trunk/include/VBox/iom.h@ 7581

Download in other formats: