|
1 /* |
|
2 * GUSEMU32 - API |
|
3 * |
|
4 * Copyright (C) 2000-2007 Tibor "TS" Schütz |
|
5 * |
|
6 * Permission is hereby granted, free of charge, to any person obtaining a copy |
|
7 * of this software and associated documentation files (the "Software"), to deal |
|
8 * in the Software without restriction, including without limitation the rights |
|
9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell |
|
10 * copies of the Software, and to permit persons to whom the Software is |
|
11 * furnished to do so, subject to the following conditions: |
|
12 * |
|
13 * The above copyright notice and this permission notice shall be included in |
|
14 * all copies or substantial portions of the Software. |
|
15 * |
|
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
|
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
|
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL |
|
19 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
|
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, |
|
21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN |
|
22 * THE SOFTWARE. |
|
23 */ |
|
24 |
|
25 #ifndef GUSEMU_H |
|
26 #define GUSEMU_H |
|
27 |
|
28 /* data types (need to be adjusted if neither a VC6 nor a C99 compatible compiler is used) */ |
|
29 |
|
30 #if defined _WIN32 && defined _MSC_VER /* doesnt support other win32 compilers yet, do it yourself... */ |
|
31 typedef unsigned char GUSbyte; |
|
32 typedef unsigned short GUSword; |
|
33 typedef unsigned int GUSdword; |
|
34 typedef signed char GUSchar; |
|
35 typedef signed short GUSsample; |
|
36 #else |
|
37 #include <stdint.h> |
|
38 typedef int8_t GUSchar; |
|
39 typedef uint8_t GUSbyte; |
|
40 typedef uint16_t GUSword; |
|
41 typedef uint32_t GUSdword; |
|
42 typedef int16_t GUSsample; |
|
43 #endif |
|
44 |
|
45 typedef struct _GUSEmuState |
|
46 { |
|
47 GUSbyte *himemaddr; /* 1024*1024 bytes used for storing uploaded samples (+32 additional bytes for read padding) */ |
|
48 GUSbyte *gusdatapos; /* (gusdataend-gusdata) bytes used for storing emulated GF1/mixer register states (32*32+4 bytes in initial GUSemu32 version) */ |
|
49 int gusirq; |
|
50 int gusdma; |
|
51 unsigned int timer1fraction; |
|
52 unsigned int timer2fraction; |
|
53 void *opaque; |
|
54 } GUSEmuState; |
|
55 |
|
56 /* ** Callback functions needed: */ |
|
57 /* NMI is defined as hwirq=-1 (not supported (yet?)) */ |
|
58 /* GUS_irqrequest returns the number of IRQs actually scheduled into the virtual machine */ |
|
59 /* Level triggered IRQ simulations normally return 1 */ |
|
60 /* Event triggered IRQ simulation can safely ignore GUS_irqclear calls */ |
|
61 int GUS_irqrequest(GUSEmuState *state, int hwirq, int num);/* needed in both mixer and bus emulation functions. */ |
|
62 void GUS_irqclear( GUSEmuState *state, int hwirq); /* used by gus_write() only - can be left empty for mixer functions */ |
|
63 void GUS_dmarequest(GUSEmuState *state); /* used by gus_write() only - can be left empty for mixer functions */ |
|
64 |
|
65 /* ** ISA bus interface functions: */ |
|
66 |
|
67 /* Port I/O handlers */ |
|
68 /* support the following ports: */ |
|
69 /* 2x0,2x6,2x8...2xF,3x0...3x7; */ |
|
70 /* optional: 388,389 (at least writes should be forwarded or some GUS detection algorithms will fail) */ |
|
71 /* data is passed in host byte order */ |
|
72 unsigned int gus_read( GUSEmuState *state, int port, int size); |
|
73 void gus_write(GUSEmuState *state, int port, int size, unsigned int data); |
|
74 /* size is given in bytes (1 for byte, 2 for word) */ |
|
75 |
|
76 /* DMA data transfer function */ |
|
77 /* data pointed to is passed in native x86 order */ |
|
78 void gus_dma_transferdata(GUSEmuState *state, char *dma_addr, unsigned int count, int TC); |
|
79 /* Called back by GUS_start_DMA as soon as the emulated DMA controller is ready for a transfer to or from GUS */ |
|
80 /* (might be immediately if the DMA controller was programmed first) */ |
|
81 /* dma_addr is an already translated address directly pointing to the beginning of the memory block */ |
|
82 /* do not forget to update DMA states after the call, including the DREQ and TC flags */ |
|
83 /* it is possible to break down a single transfer into multiple ones, but take care that: */ |
|
84 /* -dma_count is actually count-1 */ |
|
85 /* -before and during a transfer, DREQ is set and TC cleared */ |
|
86 /* -when calling gus_dma_transferdata(), TC is only set true for call transfering the last byte */ |
|
87 /* -after the last transfer, DREQ is cleared and TC is set */ |
|
88 |
|
89 /* ** GF1 mixer emulation functions: */ |
|
90 /* Usually, gus_irqgen should be called directly after gus_mixvoices if you can meet the recommended ranges. */ |
|
91 /* If the interrupts are executed immediately (i.e., are synchronous), it may be useful to break this */ |
|
92 /* down into a sequence of gus_mixvoice();gus_irqgen(); calls while mixing an audio block. */ |
|
93 /* If the interrupts are asynchronous, it may be needed to use a separate thread mixing into a temporary */ |
|
94 /* audio buffer in order to avoid quality loss caused by large numsamples and elapsed_time values. */ |
|
95 |
|
96 void gus_mixvoices(GUSEmuState *state, unsigned int playback_freq, unsigned int numsamples, GUSsample *bufferpos); |
|
97 /* recommended range: 10 < numsamples < 100 */ |
|
98 /* lower values may result in increased rounding error, higher values often cause audible timing delays */ |
|
99 |
|
100 void gus_irqgen(GUSEmuState *state, unsigned int elapsed_time); |
|
101 /* recommended range: 80us < elapsed_time < max(1000us, numsamples/playback_freq) */ |
|
102 /* lower values won´t provide any benefit at all, higher values can cause audible timing delays */ |
|
103 /* note: masked timers are also calculated by this function, thus it might be needed even without any IRQs in use! */ |
|
104 |
|
105 #endif /* gusemu.h */ |