hw/audio/gusemu.h

   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 /* doesn't 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  uint32_t gusirq;
  50  uint32_t 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 transferring 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 */