00001 /* 00002 * GUSEMU32 - API 00003 * 00004 * Copyright (C) 2000-2007 Tibor "TS" Schütz 00005 * 00006 * Permission is hereby granted, free of charge, to any person obtaining a copy 00007 * of this software and associated documentation files (the "Software"), to deal 00008 * in the Software without restriction, including without limitation the rights 00009 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 00010 * copies of the Software, and to permit persons to whom the Software is 00011 * furnished to do so, subject to the following conditions: 00012 * 00013 * The above copyright notice and this permission notice shall be included in 00014 * all copies or substantial portions of the Software. 00015 * 00016 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 00017 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 00018 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 00019 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 00020 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 00021 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 00022 * THE SOFTWARE. 00023 */ 00024 00025 #ifndef GUSEMU_H 00026 #define GUSEMU_H 00027 00028 /* data types (need to be adjusted if neither a VC6 nor a C99 compatible compiler is used) */ 00029 00030 #if defined _WIN32 && defined _MSC_VER /* doesnt support other win32 compilers yet, do it yourself... */ 00031 typedef unsigned char GUSbyte; 00032 typedef unsigned short GUSword; 00033 typedef unsigned int GUSdword; 00034 typedef signed char GUSchar; 00035 typedef signed short GUSsample; 00036 #else 00037 #include <sst_stdint.h> 00038 typedef int8_t GUSchar; 00039 typedef uint8_t GUSbyte; 00040 typedef uint16_t GUSword; 00041 typedef uint32_t GUSdword; 00042 typedef int16_t GUSsample; 00043 #endif 00044 00045 typedef struct _GUSEmuState 00046 { 00047 GUSbyte *himemaddr; /* 1024*1024 bytes used for storing uploaded samples (+32 additional bytes for read padding) */ 00048 GUSbyte *gusdatapos; /* (gusdataend-gusdata) bytes used for storing emulated GF1/mixer register states (32*32+4 bytes in initial GUSemu32 version) */ 00049 int gusirq; 00050 int gusdma; 00051 unsigned int timer1fraction; 00052 unsigned int timer2fraction; 00053 void *opaque; 00054 } GUSEmuState; 00055 00056 /* ** Callback functions needed: */ 00057 /* NMI is defined as hwirq=-1 (not supported (yet?)) */ 00058 /* GUS_irqrequest returns the number of IRQs actually scheduled into the virtual machine */ 00059 /* Level triggered IRQ simulations normally return 1 */ 00060 /* Event triggered IRQ simulation can safely ignore GUS_irqclear calls */ 00061 int GUS_irqrequest(GUSEmuState *state, int hwirq, int num);/* needed in both mixer and bus emulation functions. */ 00062 void GUS_irqclear( GUSEmuState *state, int hwirq); /* used by gus_write() only - can be left empty for mixer functions */ 00063 void GUS_dmarequest(GUSEmuState *state); /* used by gus_write() only - can be left empty for mixer functions */ 00064 00065 /* ** ISA bus interface functions: */ 00066 00067 /* Port I/O handlers */ 00068 /* support the following ports: */ 00069 /* 2x0,2x6,2x8...2xF,3x0...3x7; */ 00070 /* optional: 388,389 (at least writes should be forwarded or some GUS detection algorithms will fail) */ 00071 /* data is passed in host byte order */ 00072 unsigned int gus_read( GUSEmuState *state, int port, int size); 00073 void gus_write(GUSEmuState *state, int port, int size, unsigned int data); 00074 /* size is given in bytes (1 for byte, 2 for word) */ 00075 00076 /* DMA data transfer function */ 00077 /* data pointed to is passed in native x86 order */ 00078 void gus_dma_transferdata(GUSEmuState *state, char *dma_addr, unsigned int count, int TC); 00079 /* Called back by GUS_start_DMA as soon as the emulated DMA controller is ready for a transfer to or from GUS */ 00080 /* (might be immediately if the DMA controller was programmed first) */ 00081 /* dma_addr is an already translated address directly pointing to the beginning of the memory block */ 00082 /* do not forget to update DMA states after the call, including the DREQ and TC flags */ 00083 /* it is possible to break down a single transfer into multiple ones, but take care that: */ 00084 /* -dma_count is actually count-1 */ 00085 /* -before and during a transfer, DREQ is set and TC cleared */ 00086 /* -when calling gus_dma_transferdata(), TC is only set true for call transfering the last byte */ 00087 /* -after the last transfer, DREQ is cleared and TC is set */ 00088 00089 /* ** GF1 mixer emulation functions: */ 00090 /* Usually, gus_irqgen should be called directly after gus_mixvoices if you can meet the recommended ranges. */ 00091 /* If the interrupts are executed immediately (i.e., are synchronous), it may be useful to break this */ 00092 /* down into a sequence of gus_mixvoice();gus_irqgen(); calls while mixing an audio block. */ 00093 /* If the interrupts are asynchronous, it may be needed to use a separate thread mixing into a temporary */ 00094 /* audio buffer in order to avoid quality loss caused by large numsamples and elapsed_time values. */ 00095 00096 void gus_mixvoices(GUSEmuState *state, unsigned int playback_freq, unsigned int numsamples, GUSsample *bufferpos); 00097 /* recommended range: 10 < numsamples < 100 */ 00098 /* lower values may result in increased rounding error, higher values often cause audible timing delays */ 00099 00100 void gus_irqgen(GUSEmuState *state, unsigned int elapsed_time); 00101 /* recommended range: 80us < elapsed_time < max(1000us, numsamples/playback_freq) */ 00102 /* lower values won´t provide any benefit at all, higher values can cause audible timing delays */ 00103 /* note: masked timers are also calculated by this function, thus it might be needed even without any IRQs in use! */ 00104 00105 #endif /* gusemu.h */