iom.h@ 3291

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

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

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

Download in other formats: