iom.h@ 6981

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

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

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

Download in other formats: