iom.h@ 4672

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

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

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

Download in other formats: