iom.h@ 4014

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

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

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

Download in other formats: