iom.h@ 2596

Last change on this file since 2596 was 2504, checked in by vboxsync, 18 years ago
Documented port I/O status code and fixed places where we didn't handle them correctly. (part 1)
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 29.2 KB

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

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

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

Download in other formats: