1 /** 2 * @ingroup lib_io68 3 * @file io68/paulaemul.h 4 * @brief Paula emulator header. 5 * @author Benjamin Gerard 6 * @date 1998/07/18 7 */ 8 9 /* Copyright (c) 1998-2015 Benjamin Gerard */ 10 11 #ifndef IO68_PAULAEMUL_H 12 #define IO68_PAULAEMUL_H 13 14 #include "io68_api.h" 15 16 #include "emu68/struct68.h" 17 18 /** 19 * @defgroup lib_io68_aga Amiga Paula emulator. 20 * @ingroup lib_io68 21 * @brief Paula emulator (Amiga soundchip). 22 * 23 * @todo Write something about paula and about this emulator right here ! 24 * 25 * 26 * @par About Amiga hardware registers 27 * 28 * Amiga hardware registers could have a different address for read 29 * and write access. It is the case for DMA control register 30 * (DMACON). 31 * 32 * Registers could be (B)yte or (W)ord wide. 33 * 34 * 35 * @par SET/CLR bit 36 * 37 * Some hardware registers work with a SET/CLR bit. When writing 38 * these registers the value is not copied as is. The operation 39 * depends on the value of S the most signifiant bit (#15). 40 * 41 * - If S is 1 set-bit have to be set (bitwise OR). 42 * - If S is 0 set-bit have to be clear (bitwise NAND). 43 * 44 * 45 * @par Register map 46 * 47 * @code 48 * // NAME SZ ADDR 49 * 50 * VHPOSR (B) DFF006 [xxxxxxxx] Vertical/Horizontal electron bean position. 51 * 52 * INTREQR (W) DFF01E [-x---DCBA--------] Interrupt request read. 53 * INTREQW (W) DFF09C [-x---DCBA--------] Interrupt request write. 54 * 55 * INTENAR (W) DFF01C [-M---DCBA--------] Interrupt enable read (M=Master). 56 * INTENAW (W) DFF09A [SM---DCBA--------] Interrupt enable write (M=Master). 57 * 58 * DMACONW (W) DFF096 [S00000E00000DBCA] DMA control register write (E=Enable). 59 * DMACONR (W) DFF002 [000000E00000DBCA] DMA control register read (E=Enable). 60 * 61 * VOICEA DFF0A0 62 * VOICEB DFF0B0 63 * VOICEC DFF0C0 64 * VOICED DFF0D0 65 * 66 * VOICEX 67 * +0 (L) START [00000000 00000xxx xxxxxxxx xxxxxxx0] start address (even). 68 * +4 (W) LENGTH [xxxxxxxx xxxxxxxx] Length in word (0=010000). 69 * +6 (W) PERIOD [0000xxxx xxxxxxxx] Period (in paula cycle). 70 * +8 (W) VOLUME [0xxxxxxx] Volume [0-64] (presume value > 64 => 64). 71 * @endcode 72 * 73 * 74 * @{ 75 */ 76 77 /** 78 * Amiga hardware regiosters. 79 */ 80 enum amiga_regs_e { 81 82 /** Amiga Vertical/Horizontal electron bean position */ 83 PAULA_VHPOSR = 0x06, 84 85 /** 86 * @name Amiga interrupt registers. 87 * 88 * All hardware registers involved with interruption handling use the 89 * same bit organisation : 90 * - bit 7 Audio channel A 91 * - bit 8 Audio channel B 92 * - bit 9 Audio channel C 93 * - bit 10 Audio channel D 94 * - bit 14 Master interrupt 95 * @{ 96 */ 97 PAULA_INTREQR = 0x1E, /**< Interruption request read */ 98 PAULA_INTREQRH = 0x1E, /**< Interruption request read MSB */ 99 PAULA_INTREQRL = 0x1F, /**< Interruption request read LSB */ 100 101 PAULA_INTREQ = 0x9C, /**< Interruption request write */ 102 PAULA_INTREQH = 0x9C, /**< Interruption request write MSB */ 103 PAULA_INTREQL = 0x9D, /**< Interruption request write LSB */ 104 105 PAULA_INTENAR = 0x1C, /**< Interruption enable read */ 106 PAULA_INTENARH = 0x1C, /**< Interruption enable read MSB */ 107 PAULA_INTENARL = 0x1D, /**< Interruption enable read LSB */ 108 109 PAULA_INTENA = 0x9A, /**< Interruption enable write */ 110 PAULA_INTENAH = 0x9A, /**< Interruption enable write MSB */ 111 PAULA_INTENAL = 0x9B, /**< Interruption enable write LSB */ 112 /** 113 * @} 114 */ 115 116 /** 117 * @name Amiga DMA registers. 118 * 119 * Amiga DMA control register bits : 120 * - bit 0 Audio DMA channel A 121 * - bit 1 Audio DMA channel B 122 * - bit 2 Audio DMA channel C 123 * - bit 3 Audio DMA channel D 124 * - bit 9 General DMA 125 * 126 * @{ 127 */ 128 PAULA_DMACONR = 0x02, /**< DMA control read */ 129 PAULA_DMACONRH = 0x02, /**< DMA control read MSB */ 130 PAULA_DMACONRL = 0x03, /**< DMA control read LSB */ 131 PAULA_DMACON = 0x96, /**< DMA control write */ 132 PAULA_DMACONH = 0x96, /**< DMA control write MSB */ 133 PAULA_DMACONL = 0x97, /**< DMA control write LSB */ 134 /** 135 * @} 136 */ 137 138 /** 139 * @name The Audio & Disk Control Registers. 140 * 141 * Bits: 142 * - 07 USE3PN Use audio channel 3 to modulate nothing. 143 * - 06 USE2P3 Use audio channel 2 to modulate period of channel 3. 144 * - 05 USE1P2 Use audio channel 1 to modulate period of channel 2. 145 * - 04 USE0P1 Use audio channel 0 to modulate period of channel 1. 146 * - 03 USE3VN Use audio channel 3 to modulate nothing. 147 * - 02 USE2V3 Use audio channel 2 to modulate volume of channel 3. 148 * - 01 USE1V2 Use audio channel 1 to modulate volume of channel 2. 149 * - 00 USE0V1 Use audio channel 0 to modulate volume of channel 1. 150 * 151 * @note If both period/volume are modulated on the same channel, the 152 * period and volume will be alternated. First word xxxxxxxx V6-V0, 153 * Second word P15-P0 (etc). 154 * 155 * @{ 156 */ 157 PAULA_ADKCON = 0x9E, /**< Audio, disk, control write. */ 158 PAULA_ADKCONR = 0x10, /**< Audio, disk, control read. */ 159 PAULA_ADKCONRH = PAULA_ADKCONR+0, 160 PAULA_ADKCONRL = PAULA_ADKCONR+1, 161 /** 162 * @} 163 */ 164 165 /** 166 * @name Amiga Paula registers. 167 * @{ 168 */ 169 PAULA_VOICEA = 0xA0, /**< Paula channel A register base. */ 170 PAULA_VOICEB = 0xB0, /**< Paula channel B register base. */ 171 PAULA_VOICEC = 0xC0, /**< Paula channel C register base. */ 172 PAULA_VOICED = 0xD0, /**< Paula channel D register base. */ 173 /** 174 * @} 175 */ 176 }; 177 178 #define PAULA_VOICE(I) ((0xA+(I))<<4) /**< Paula channel I register base. */ 179 180 /** 181 * Amiga Paula Clock frequencies. 182 */ 183 enum { 184 PAULA_PAL_FRQ = 3546897u, /**< Paula PAL clock frequency. */ 185 PAULA_NTSC_FRQ = 3579545u, /**< Paula NTSC clock frequency. */ 186 }; 187 188 /** 189 * Type used by internal counters. 190 * 191 * This type must be an unsigned of at least 32-bit. Values are 192 * always fixed point. The amount of shifting is calculated so that 193 * the most useful bit is the most signifiant bit. Therefore these 194 * counters have a automatic natural modulo. 195 */ 196 typedef uint68_t plct_t; 197 198 /** Must be same size than plct_t but signed. */ 199 typedef int68_t signed_plct_t; 200 201 /** Paula voice data structure. */ 202 typedef struct { 203 plct_t adr; /**< current sample counter (<<paula_t::ct_fix). */ 204 plct_t start; /**< loop address. */ 205 plct_t end; /**< end address (<<paula_t::ct_fix). */ 206 } paulav_t; 207 208 /** Paula emulator data structure. */ 209 typedef struct { 210 u8 map[256]; /**< Paula regiters mapping. */ 211 paulav_t voice[4]; /**< Paula voices (4 channels). */ 212 int engine; /**< @ref paula_engine_e "Engine id". */ 213 int ct_fix; /**< Fixed precision used by counters in 214 order to have a natural memory access 215 modulo. */ 216 int clock; /**< Clock type. @see paula_clock_e. */ 217 plct_t clkperspl; /**< (clock<<paula_t::ct_fix)/hz. */ 218 uint_t hz; /**< Sampling rate in hz, */ 219 int * chansptr; /**< Pointer to enabled channels mask. */ 220 221 const u8 * mem; /**< 68K memory buffer. */ 222 int log2mem; /**< 68K memory buffer size (2^log2mem). */ 223 224 int dmacon; /**< Shadow DMACON. */ 225 int intena; /**< Shadow INTENA. */ 226 int intreq; /**< Shadow INTREQ. */ 227 int adkcon; /**< Shadow ADKCON. */ 228 int vhpos; /**< Shadow VHPOSR. */ 229 } paula_t; 230 231 /** 232 * @name Initialization functions. 233 * @{ 234 */ 235 236 /** available emulation modes. */ 237 enum paula_engine_e { 238 PAULA_ENGINE_QUERY = -1, /**< Query current or default paula engine. */ 239 PAULA_ENGINE_DEFAULT = 0, /**< Default engine. */ 240 PAULA_ENGINE_SIMPLE, /**< Without interpolation. */ 241 PAULA_ENGINE_LINEAR /**< With linear interpolation. */ 242 }; 243 244 /** clock type. */ 245 enum paula_clock_e { 246 PAULA_CLOCK_QUERY = -1, /**< Query current or default clock */ 247 PAULA_CLOCK_DEFAULT = 0, 248 PAULA_CLOCK_PAL, 249 PAULA_CLOCK_NTSC 250 }; 251 252 /** sampling rate value in hertz. */ 253 enum paula_hz_e { 254 PAULA_HZ_QUERY = -1, /**< Query current or default sampling rate */ 255 PAULA_HZ_DEFAULT = 0 /**< Default sampling rate */ 256 }; 257 258 /** Paula instance creaation parameters. */ 259 typedef struct { 260 int engine; /**< Default @ref paula_engine_e "emulation mode". */ 261 int clock; /**< Default @ref paula_clock_e "clock type". */ 262 int hz; /**< Default @ref paula_hz_e "sampling rate" in Hz. */ 263 } paula_parms_t; 264 265 /** setup data. */ 266 typedef struct { 267 paula_parms_t parms; /**< Paula params. */ 268 const u8 * mem; /**< 68K memory buffer. */ 269 int log2mem; /**< 68K memory buffer size (2^log2mem). */ 270 } paula_setup_t; 271 272 IO68_EXTERN 273 /** 274 * Init paula library. 275 * 276 * The paula_init() must be call prior to all other paula functions. 277 * 278 * @return error-code (always success) 279 * @return 0 Success 280 * @return -1 Failure 281 * 282 * @see paula_shutdown() 283 */ 284 int paula_init(int * argc, char ** argv); 285 286 IO68_EXTERN 287 /** 288 * Shutdown paula library. 289 * 290 * @see paula_init() 291 */ 292 void paula_shutdown(void); 293 294 IO68_EXTERN 295 /** 296 * Paula hardware reset. 297 * 298 * The paula_reset() reset function perform a Paula reset. 299 * It performs following operations : 300 * - all registers zeroed 301 * - all internal voices set to dummy 2 samples len address. 302 * - general DMA enabled 303 * - all audio DMA disabled 304 * - interrupt master enabled 305 * - all audio interrupt disbled 306 * 307 * @return error-code (always success) 308 * @return 0 Success 309 */ 310 int paula_reset(paula_t * const paula); 311 312 IO68_EXTERN 313 /** 314 * Paula emulator instance setup. 315 * 316 * @return error-code (always success) 317 * @return 0 Success 318 * 319 * @see paula_reset() 320 */ 321 int paula_setup(paula_t * const paula, paula_setup_t * const setup); 322 323 IO68_EXTERN 324 /** 325 * Paula emulator instance cleanup. 326 */ 327 void paula_cleanup(paula_t * const paula); 328 329 IO68_EXTERN 330 /** 331 * Set/Get paula emulator type. 332 * 333 * The paula_emulation() function set and get the paula emulator 334 * type. 335 * 336 * If engine is paula_engine_e::PAULA_ENGINE_QUERY the function 337 * returns the current value without modifying anything. Else the 338 * function set the current paula engine according to the value of 339 * engine. If paula parameter is NULL pointer the function works 340 * with the default parameters rather than a actual paula instance 341 * meaning it will read or write the default setting (addressed by 342 * paula_engine_e::PAULA_ENGINE_DEFAULT). 343 * 344 * @param paula Paula emulator instance. 345 * @param engine @ref paula_engine_e "emulator type". 346 * @return an @ref paula_engine_e "emulator type". 347 */ 348 int paula_engine(paula_t * const paula, int engine); 349 350 IO68_EXTERN 351 /** 352 * Set/Get paula clock type. 353 * 354 * The paula_clock() function is similar to the paula_engine() 355 * function except it concerns clock rate. 356 * 357 * @param paula Paula emulator instance. 358 * @param clock @ref paula_clock_e "clock type". 359 * @return a @ref paula_clock_e "clock type". 360 */ 361 int paula_clock(paula_t * const paula, int clock); 362 363 IO68_EXTERN 364 /** 365 * Set/Get paula emulator sampling rate. 366 * 367 * The paula_sampling_rate() function is similar to the 368 * paula_engine() function except it concerns sampling rate. 369 * 370 * @param paula Paula emulator instance. 371 * @param hz @ref paula_hz_e "sampling rate" in Hz. 372 * @return actual @ref paula_hz_e "sampling rate" in Hz. 373 */ 374 int paula_sampling_rate(paula_t * const paula, int hz); 375 376 /** 377 * @} 378 */ 379 380 381 /** 382 * @name Emulation functions 383 * @{ 384 */ 385 386 IO68_EXTERN 387 /** 388 * Execute Paula emulation. 389 * 390 * The paula_mix() function processes sample mixing with current 391 * internal parameters for n samples. Mixed samples are stored in a 392 * large enough (at least n) 32 bit pcm buffer pointed by b. mem68 393 * is a pointer to the 68K memory buffer. The Paula emulator assume 394 * that this buffer is at least the size of the Amiga "chip" 395 * RAM. This implies at leat 512Kb and PCM data must be in the first 396 * 512Kb. 397 * 398 * @param paula Paula emulator instance 399 * @param splbuf Destination 32-bit sample buffer 400 * @param n Number of sample to mix in splbuf buffer 401 * 402 */ 403 void paula_mix(paula_t * const paula, s32 * splbuf, int n); 404 405 /** 406 * @} 407 */ 408 409 /** 410 * @} 411 */ 412 413 #endif 414