1
Atari POKEY Chip Emulator V2.0
2
==============================
6
The PokeySound Chip Emulator is designed to emulate the functionality of the
7
Atari POKEY Chip Hardware through 'C' Sourcecode. The emulator is able to
8
produce sounds which are essentially identical to the original POKEY chip,
9
including the exact distortions and pitches.
11
The emulator is designed to run in a 32-bit environment. Though it can be
12
compiled and run in a 16-bit environment, it is slow.
14
I would like to give special thanks to Neil Bradley. He provided excellent
15
testing support and was also the driving force behind the multiple POKEY
21
Version 2.0 of the 'PokeySound' adds the following features:
23
1) Support for multiple POKEY chips. The maximum supported is configured
26
2) An adjustable gain. The previous releases had a built-in gain of 64.
28
3) A clipping option. Depending on the number of chips emulated and the
29
configured gain, it is possible for the output to exceed 8-bits.
30
Clipping can be enabled to prevent this, though it does increase the
37
The 'PokeySound' emulator supports the following functions:
39
1) All polynomial sound generators:
40
a) 4-bit poly - actual bit pattern determined from sampled sound
41
b) 5-bit poly - actual bit pattern determined from sampled sound
42
c) 17-bit poly - simulated random bit pattern
43
d) 9-bit poly - derived from simulated 17-bit poly
45
2) Full support of all 'Divide by N' counter clocks:
46
a) 1.79 MHz (high limited to playback sample rate)
47
b) 64 KHz (high limited to playback sample rate)
50
3) Full support of all 'Divide by N' resolutions:
51
a) 8-bit - single channel
52
b) 16-bit - double channel
54
4) Full support of all distortions
55
a) 5-bit poly, then 17-bit poly
57
c) 5-bit poly, then 4-bit poly
59
e) no poly counters (pure tone)
62
5) Full support of volume control
64
6) Full support of all pitches - distortions will vary exactly as the
65
original Atari based on different pitches
67
7) Accurate pitch generation
69
8) Support of any playback sample rate (e.g. 22050)
72
The 'PokeySound' emulator does not currently support the following functions:
77
Though I don't believe adding support for the High-Pass filters is very
78
complicated, I decided not to add support right now because I don't
79
believe this feature is used much. I'm also not sure how much impact it
80
would have on performance. Let me know if you find an application that
83
In the 2.0 release, I've removed the non-optimized vrersion. It was only
84
left in for reference. If you would still like to see the non-optimized
85
version, it's available in the 1.2 release.
87
One of the unique features of the emulator is that the processing time varies
88
based on the frequency. Since the routine only calculates new output values
89
when a change is sensed, the lower frequencies (which change less frequently)
90
will require less processing time.
93
Differences Between the Emulator and the Actual POKEY Chip:
94
-----------------------------------------------------------
96
The biggest difference between the emulator and the original hardware is
97
that the emulator emulates an 'ideal' POKEY chip. All output from the
98
emulator is a based on a precise square wave, whereas the output from the
99
original chip has decay. Though the output is slightly different, I
100
don't believe this difference is easily discernible.
102
Another slight difference is the 17-bit/9-bit poly. Since the polynomial
103
is large (2^17 bits), I choose to create the sample using a random number
104
generator rather than a table. I don't believe this difference is
107
There are also a few differences which are introduced by aliasing. This is
108
a direct result of using an output sampling rate which is not identical to
109
the original sound rate. It is most evident with high frequencies.
111
A final difference is the lack of support for the High-Pass Filter
112
functionality. I plan to add this in a future release if necessary.
115
Sample/Test Application:
116
------------------------
118
The test program I've distributed is a 16-bit DOS application created with
119
the Borland 'C' compiler. The only reason I used 16-bit was because I
120
already had a set of working SB drivers in 16-bit. Since the test system
121
is dedicated to generating sounds, the performance in 16-bit is more than
128
The POKEY.C file is the heart of the PokeySound Emulation program.
129
Although the routines in the file must work together, no other files are
130
modules are required for operation. A header file, 'POKEY.H', has
131
been included for use in other modules, and provides the necessary
132
function prototypes. I've attempted to make the routines as portable as
133
possible, so the file should compile on almost any compiler with little
136
I have made some attempts at optimizing the routines, though I am sure
137
more optimization can be done. They are currently only available in 'C'.
138
I'll be happy to convert them to assembly language if desired. Please feel
139
free to send me e-mail at rfries@tcmail.frco.com.
141
The routines are easy to use. Detailed descriptions on the function calls
144
The POKEY.C module can be compiled in a 32-bit or 16-bit environment.
145
Since these routines are optimized for 32-bit use, the code will default
146
to 32-bit. To compile in 16-bits, use a command line option to define
153
On start-up of the system, a single call should be made to Pokey_sound_init.
154
This routine will prepare the structures for sound output. This routine
155
can be called again if necessary during warm-start or other reset.
157
Once in the main loop, there are two other functions that will be used.
158
Whenever the system needs to write to either the AUDC or AUDF values,
159
a call should be made to the Update_pokey_sound routine. This routine will
160
take care of updating the internal registers. It will pre-calculate several
161
values to help with optimization.
163
The only other routine that is called is the Pokey_process function. This
164
function will fill a audio buffer with a specified number of bytes. This
165
function should be called whenever a new audio buffer is required.
167
For best results, I recommend using at least two output buffers. Using this
168
scheme, the sound card can be playing one buffer while the system is filling
172
DETAILED FUNCTION DESCRIPTIONS
173
------------------------------
175
Pokey_sound_init(uint32 freq17, uint16 playback_freq, uint8 num_pokeys)
176
-----------------------------------------------------------------------
178
This function initializes the structures used by the PokeySound routines.
179
This function takes three parameters: the main clock frequency, the
180
playback frequency and the number of POKEY chips to emulate.
182
The maximum number of POKEY chips emulated is configured at compile time.
183
Though the maximum number of chips can be configured as one, the PokeySound
184
1.2 routines are recommended if only a single chip is to be emulated since
185
they have will provide better performance.
187
The main clock frequency is the frequency of the 1.79MHz source clock.
188
To provide exact results, freq17 should be set equal to 1789790 Hz. As an
189
alternative, freq17 can be set to an approximate frequency of 1787520 Hz.
190
Using this approximate frequency will reduce aliasing and thus produce a
191
clearer output signal.
193
A constant has been defined for both of these values for your convenience.
194
The names are FREQ_17_EXACT and FREQ_17_APPROX.
196
The playback frequency is the frequency of the sound playback (the frequency
197
used by the sound card). For best results, the playback frequency should
198
be an even division of the main clock frequency. Since most of the sounds
199
will be generated using the 64kHz clock, I also recommend making the
200
playback frequency an even division of the 64kHz clock.
202
The 64kHz clock is exactly equal to the main clock divided by 28. For
203
the playback frequency, I recommend one of the following values:
205
1) FREQ_17_APPROX / (28*1), which is equal to 63840. Of course, most sound
206
cards can't reproduce this frequency.
208
2) FREQ_17_APPROX / (28*2), which is equal to 31920. All of the newer cards
209
will support this frequency.
211
3) FREQ_17_APPROX / (28*3), which is equal to 21280. All of the SB
212
compatibles should support this frequency.
214
4) FREQ_17_APPROX / (28*4), which is equal to 15960. This may be the
215
best choice, as it offers good sound reproduction with good performance.
217
Of course, these options also assume you are using the approximate
218
frequency for the main clock as well. Any of these choices will offer the
219
best results when the main 64kHz clock is used, reasonable results when the
220
15kHz clock is selected, and marginal results when the 1.79MHz clock is
221
selected (the only way to produce good results in all cases is to set the
222
playback frequency to 1.79MHz!)
224
Feel free to experiment to find other alternatives as well.
226
This function has no return value (void).
229
Update_pokey_sound (uint16 addr, uint8 val, uint8 chip, uint8 gain)
230
-------------------------------------------------------------------
232
This function should be called each time an AUDC, AUDF or AUDCTL value
233
changes. This function takes four parameters: the address to change,
234
the new value, the chip to be updated, and the gain to be used.
235
The lower four bits of the address should be one of the following values:
249
In order to support multiple POKEY chips, only the lower four bits of
250
the address are used. Note that this routine can no longer be called with
251
any address as it will affect the operation of the specified chip.
253
The routine pre-calculates several values that are needed by the
254
processing function. This is done to optimize performance.
256
The output will be amplified (multiplied) by gain/16 (previous releases had
257
a built in multiplier of 4, which calculates to a gain value of 64). If the
258
output exceeds the maximum value after then gain and clipping is enabled,
259
the output will be limited to reduce distortion.
261
The best value for the gain depends on the number of POKEYs emulated and
262
the maximum volume used. The maximum possible output for each channel is 15,
263
making the maximum possible output for a single chip to be 60. Assuming all
264
four channels on the chip are used at full volume, a gain of 64 can be used
265
without distortion. If 4 POKEY chips are emulated and all 16 channels are
266
used at full volume, the gain must be no more than 16 to prevent distortion.
267
Of course, if only a few of the 16 channels are used or not all channels are
268
used at full volume, a larger gain can be used.
270
To enable clipping, define the logical CLIP before compiling. This is the
271
default mode of operation as it has already been included in the POKEY.H file.
272
Note that this is only recommended if clipping is necessary since it will
273
impact the performance.
275
This function has no return value (void).
278
Pokey_process (uint8 *buffer, uint16 n)
279
---------------------------------------
281
This function calculates and fills a buffer with unsigned 8-bit mono audio.
282
This function takes two parameters: a pointer to the buffer to fill and
283
the size of the buffer (limited to 65535). This function fills the
284
buffer based on the requested size and returns. It automatically
285
updates the pointers for the next call, so subsequent calls to this function
286
will provide a continuous stream of data.
288
The size of the buffer that is needed depends on the playback frequency.
289
It is best to keep the buffer as small as possible to maximize response time
290
to changes in the sound. Of course, the minimum size is dependent on
291
system and emulator performance.
293
Selecting the correct buffer size is a careful balance. Selecting a buffer
294
size that is too small will produce noticeable clicks in the output, though
295
selecting a size that is too large will cause a poor response time and
296
possible delays in the system when the new buffer is filled.
298
This function has no return value (void).
301
License Information and Copyright Notice
302
========================================
304
PokeySound is Copyright(c) 1996-1997 by Ron Fries
306
This library is free software; you can redistribute it and/or modify it under
307
the terms of version 2 of the GNU Library General Public License as published
308
by the Free Software Foundation.
310
This library is distributed in the hope that it will be useful, but WITHOUT
311
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
312
FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more
315
To obtain a copy of the GNU Library General Public License, write to the Free
316
Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
318
Any permitted reproduction of these routines, in whole or in part, must bear