git.sur5r.net Git - cc65/blob - include/_pokey.h

   1 /*****************************************************************************/
   2 /*                                                                           */
   3 /*                                 _pokey.h                                  */
   4 /*                                                                           */
   5 /*                Internal include file, do not use directly                 */
   6 /*                                                                           */
   7 /* POKEY, Pot Keyboard Integrated Circuit, is a digital I/O chip designed    */
   8 /* for the Atari 8-bit family of home computers; it combines functions for   */
   9 /* sampling (ADC) potentiometers (such as game paddles) and scan matrices of */
  10 /* switches (such as a computer keyboard) as well as sound generation.       */
  11 /* It produces four voices of distinctive square wave sound, either as clear */
  12 /* tones or modified with a number of distortion settings. - Wikipedia       */
  13 /* "POKEY" article.                                                          */
  14 /*                                                                           */
  15 /*                                                                           */
  16 /* (C) 2000 Freddy Offenga <taf_offenga@yahoo.com>                           */
  17 /* 2019-01-14: Bill Kendrick <nbs@sonic.net>: More defines for registers     */
  18 /*                                                                           */
  19 /*                                                                           */
  20 /* This software is provided 'as-is', without any expressed or implied       */
  21 /* warranty.  In no event will the authors be held liable for any damages    */
  22 /* arising from the use of this software.                                    */
  23 /*                                                                           */
  24 /* Permission is granted to anyone to use this software for any purpose,     */
  25 /* including commercial applications, and to alter it and redistribute it    */
  26 /* freely, subject to the following restrictions:                            */
  27 /*                                                                           */
  28 /* 1. The origin of this software must not be misrepresented; you must not   */
  29 /*    claim that you wrote the original software. If you use this software   */
  30 /*    in a product, an acknowledgment in the product documentation would be  */
  31 /*    appreciated but is not required.                                       */
  32 /* 2. Altered source versions must be plainly marked as such, and must not   */
  33 /*    be misrepresented as being the original software.                      */
  34 /* 3. This notice may not be removed or altered from any source              */
  35 /*    distribution.                                                          */
  36 /*                                                                           */
  37 /*****************************************************************************/
  38
  39
  40
  41 #ifndef __POKEY_H
  42 #define __POKEY_H
  43
  44
  45
  46 /* Define a structure with the POKEY register offsets for write (W) */
  47 struct __pokey_write {
  48     unsigned char   audf1;  /* audio channel #1 frequency */
  49     unsigned char   audc1;  /* audio channel #1 control */
  50     unsigned char   audf2;  /* audio channel #2 frequency */
  51     unsigned char   audc2;  /* audio channel #2 control */
  52     unsigned char   audf3;  /* audio channel #3 frequency */
  53     unsigned char   audc3;  /* audio channel #3 control */
  54     unsigned char   audf4;  /* audio channel #4 frequency */
  55     unsigned char   audc4;  /* audio channel #4 control */
  56     unsigned char   audctl; /* audio control */
  57     unsigned char   stimer; /* start pokey timers */
  58
  59     unsigned char   skrest;
  60     /* reset serial port status reg.;
  61     ** Reset BITs 5 - 7 of the serial port status register (SKCTL) to "1"
  62     */
  63
  64     unsigned char   potgo;  /* start paddle scan sequence (see "ALLPOT") */
  65     unsigned char   unuse1; /* unused */
  66     unsigned char   serout; /* serial port data output */
  67     unsigned char   irqen;  /* interrupt request enable */
  68     unsigned char   skctl;  /* serial port control */
  69 };
  70
  71
  72
  73 /* AUDC1-4 register values */
  74
  75 /* Meaningful values for the distortion bits.
  76 ** The first process is to divide the clock value by the frequency,
  77 ** then mask the output using the polys in the order below;
  78 ** finally, the result is divided by two.
  79 */
  80 #define AUDC_POLYS_5_17  0x00
  81 #define AUDC_POLYS_5     0x20 /* Same as 0x60 */
  82 #define AUDC_POLYS_5_4   0x40
  83 #define AUDC_POLYS_17    0x80
  84 #define AUDC_POLYS_NONE  0xA0 /* Same as 0xE0 */
  85 #define AUDC_POLYS_4     0xC0
  86
  87 /* When set, the volume value in AUDC1-4 bits 0-3 is sent directly to the speaker;
  88 ** it is not modulated with the frequency specified in the AUDF1-4 registers.
  89 ** (See "De Re Atari" Chapter 7: Sound)
  90 */
  91 #define AUDC_VOLUME_ONLY 0x10
  92
  93
  94 /* AUDCTL register values */
  95
  96 #define AUDCTL_CLOCKBASE_15HZ     0x01 /* Switch main clock base from 64 KHz to 15 KHz */
  97 #define AUDCTL_HIGHPASS_CHAN2     0x02 /* Insert high pass filter into channel two, clocked by channel four */
  98 #define AUDCTL_HIGHPASS_CHAN1     0x04 /* Insert high pass filter into channel one, clocked by channel two */
  99 #define AUDCTL_JOIN_CHAN34        0x08 /* Join channels four and three (16 bit) */
 100 #define AUDCTL_JOIN_CHAN12        0x10 /* Join channels two and one (16 bit) */
 101 #define AUDCTL_CLOCK_CHAN3_179MHZ 0x20 /* Clock channel three with 1.79 MHz */
 102 #define AUDCTL_CLOCK_CHAN1_179MHZ 0x40 /* Clock channel one with 1.79 MHz */
 103 #define AUDCTL_9BIT_POLY          0x80 /* Makes the 17 bit poly counter into nine bit poly (see also: RANDOM) */
 104
 105
 106 /* IRQEN register values */
 107
 108 #define IRQEN_TIMER_1                  0x01 /* The POKEY timer one interrupt is enabled */
 109 #define IRQEN_TIMER_2                  0x02 /* The POKEY timer two interrupt is enabled */
 110 #define IRQEN_TIMER_4                  0x04 /* The POKEY timer four interrupt is enabled */
 111 #define IRQEN_SERIAL_TRANS_FINISHED    0x08 /* The serial out transmission finished interrupt is enabled */
 112 #define IRQEN_SERIAL_OUT_DATA_REQUIRED 0x10 /* The serial output data required interrupt is enabled */
 113 #define IRQEN_SERIAL_IN_DATA_READY     0x20 /* The serial input data ready interrupt is enabled. */
 114 #define IRQEN_OTHER_KEY                0x40 /* The "other key" interrupt is enabled */
 115 #define IRQEN_BREAK_KEY                0x80 /* The BREAK key is enabled */
 116
 117
 118 /* SKCTL register values */
 119
 120 #define SKCTL_KEYBOARD_DEBOUNCE 0x01 /* Enable keyboard debounce circuits */
 121 #define SKCTL_KEYBOARD_SCANNING 0x02 /* Enable keyboard scanning circuit */
 122
 123 #define SKCTL_FAST_POT_SCAN     0x04 /* Fast pot scan */
 124 /* The pot scan counter completes its sequence in two TV line times instead of
 125 ** one frame time (228 scan lines). Not as accurate as the normal pot scan
 126 */
 127
 128 #define SKCTL_TWO_TONE_MODE     0x08 /* POKEY two-tone mode */
 129 /* Serial output is transmitted as a two-tone signal rather than a logic true/false. */
 130
 131
 132 /* Bits 4, 5, and 6 of SKCTL set Serial Mode Control: */
 133
 134 #define SKCTL_SER_MODE_TX_EXT_RX_EXT       0x00
 135 /* Trans. & Receive rates set by external clock; Also internal clock phase reset to zero. */
 136
 137 #define SKCTL_SER_MODE_TX_EXT_RX_ASYNC     0x10
 138 /* Trans. rate set by external clock; Receive asynch. (ch. 4) (CH3 and CH4). */
 139
 140 #define SKCTL_SER_MODE_TX_CH4_RX_CH4_BIDIR 0x20
 141 /* Trans. & Receive rates set by Chan. 4; Chan. 4 output on Bi-Direct. clock line. */
 142
 143 /* N.B.: Bit combination 0,1,1 not useful */
 144
 145 #define SKCTL_SER_MODE_TX_CH4_RX_EXT       0x40
 146 /* Trans. rate set by Chan. 4; Receive rate set by external clock. */
 147
 148 /* N.B.: Bit combination 1,0,1 not useful */
 149
 150 #define SKCTL_SER_MODE_TX_CH2_RX_CH4_BIDIR 0x60
 151 /* Trans. rate set by Chan. 2; Receive rate set by Chan. 4; Chan. 4 out on Bi-Direct. clock line. */
 152
 153 #define SKCTL_SER_MODE_TX_CH4_RX_ASYNC     0x70
 154 /* Trans. rate set by Chan. 2; Receive asynch. (chan 3 & 4); Bi-Direct. clock not used (tri-state condition). */
 155
 156
 157 #define SKCTL_FORCE_BREAK       0x80 /* Force break (serial output to zero) */
 158
 159
 160 /* Define a structure with the POKEY register offsets for read (R) */
 161 struct __pokey_read {
 162     unsigned char   pot0;   /* paddle 0 value */
 163     unsigned char   pot1;   /* paddle 1 value */
 164     unsigned char   pot2;   /* paddle 2 value */
 165     unsigned char   pot3;   /* paddle 3 value */
 166     unsigned char   pot4;   /* paddle 4 value */
 167     unsigned char   pot5;   /* paddle 5 value */
 168     unsigned char   pot6;   /* paddle 6 value */
 169     unsigned char   pot7;   /* paddle 7 value */
 170     unsigned char   allpot; /* eight paddle port status (see "POTGO") */
 171     unsigned char   kbcode; /* keyboard code */
 172     unsigned char   random; /* random number generator */
 173     unsigned char   unuse2; /* unused */
 174     unsigned char   unuse3; /* unused */
 175     unsigned char   serin;  /* serial port input */
 176     unsigned char   irqst;  /* interrupt request status */
 177     unsigned char   skstat; /* serial port status */
 178 };
 179
 180
 181 /* SKSTAT register values */
 182 #define SKSTAT_SERIN_SHIFTREG_BUSY         0x02 /* Serial input shift register busy */
 183 #define SKSTAT_LASTKEY_PRESSED             0x04 /* the last key is still pressed */
 184 #define SKSTAT_SHIFTKEY_PRESSED            0x08 /* the [Shift] key is pressed */
 185 #define SKSTAT_DATA_READ_INGORING_SHIFTREG 0x10 /* Data can be read directly from the serial input port, ignoring the shift register. */
 186 #define SKSTAT_KEYBOARD_OVERRUN            0x20 /* Keyboard over-run; Reset BITs 7, 6 and 5 (latches) to 1, using SKREST */
 187 #define SKSTAT_INPUT_OVERRUN               0x40 /* Serial data input over-run. Reset latches as above. */
 188 #define SKSTAT_INPUT_FRAMEERROR            0x80 /* Serial data input frame error caused by missing or extra bits. Reset latches as above. */
 189
 190
 191 /* KBCODE internal keyboard codes for Atari 8-bit computers*/
 192
 193 /* Defined below in the order the keys appear on a 1200XL keyboard,
 194 ** from top left to bottom right.
 195 ** Note: Numerous Shift+Ctrl+key combos are unavailable.
 196 ** (Source: "Compute!'s Thrid Book of Atari", "Reading the Keyboard Codes")
 197 */
 198
 199 #define KEYCODE_NONE      255 /* No key pressed (but also Ctrl+Shift+A) */
 200
 201
 202 /* Special keys: */
 203
 204 /* N.B. Reset key not handled like other keys */
 205
 206 /* N.B. Select, Start, and Option console keys not handled like other keys;
 207 ** see CONSOL register in GTIA
 208 */
 209
 210 /* Fn (function) keys only available on 1200XL */
 211 #define KEYCODE_F1        3
 212 #define KEYCODE_F2        4
 213 #define KEYCODE_F3        19
 214 #define KEYCODE_F4        20
 215
 216 /* HELP key only available on XL/XE series */
 217 #define KEYCODE_HELP      17
 218
 219 /* N.B. Break key not handled like other keys */
 220
 221
 222 /* Keyboard top row */
 223
 224 #define KEYCODE_ESC       28
 225 #define KEYCODE_1         31
 226 #define KEYCODE_2         30
 227 #define KEYCODE_3         26
 228 #define KEYCODE_4         24
 229 #define KEYCODE_5         29
 230 #define KEYCODE_6         27
 231 #define KEYCODE_7         51
 232 #define KEYCODE_8         53
 233 #define KEYCODE_9         48
 234 #define KEYCODE_0         50
 235 #define KEYCODE_LT        54
 236 #define KEYCODE_GT        55
 237 #define KEYCODE_BKSPC     52
 238
 239
 240 /* Keyboard second row */
 241
 242 #define KEYCODE_TAB       44
 243 #define KEYCODE_Q         47
 244 #define KEYCODE_W         46
 245 #define KEYCODE_E         42
 246 #define KEYCODE_R         40
 247 #define KEYCODE_T         45
 248 #define KEYCODE_Y         43
 249 #define KEYCODE_U         11
 250 #define KEYCODE_I         13
 251 #define KEYCODE_O         8
 252 #define KEYCODE_P         10
 253 #define KEYCODE_MINUS     14
 254 #define KEYCODE_EQUALS    15
 255 #define KEYCODE_RETURN    12
 256
 257
 258 /* Keyboard third row */
 259
 260 #define KEYCODE_CTRL      128 /* binary OR'd */
 261 /* N.B. Cannot read Ctrl key alone */
 262
 263 #define KEYCODE_A         63
 264 #define KEYCODE_S         62
 265 #define KEYCODE_D         58
 266 #define KEYCODE_F         56
 267 #define KEYCODE_G         61
 268 #define KEYCODE_H         57
 269 #define KEYCODE_J         1
 270 #define KEYCODE_K         5
 271 #define KEYCODE_L         0
 272 #define KEYCODE_SEMICOLON 2
 273 #define KEYCODE_PLUS      6
 274 #define KEYCODE_ASTERISK  7
 275 #define KEYCODE_CAPS      60
 276
 277
 278 /* Keyboard bottom row */
 279
 280 #define KEYCODE_SHIFT     64 /* binary OR'd */
 281 /* N.B. Cannot read Shift key alone via KBCODE;
 282 ** instead, check "Shfit key press" bit of SKSTAT register
 283 */
 284
 285 #define KEYCODE_Z         23
 286 #define KEYCODE_X         22
 287 #define KEYCODE_C         18
 288 #define KEYCODE_V         16
 289 #define KEYCODE_B         21
 290 #define KEYCODE_N         35
 291 #define KEYCODE_M         37
 292 #define KEYCODE_COMMA     32
 293 #define KEYCODE_PERIOD    34
 294 #define KEYCODE_SLASH     38
 295 #define KEYCODE_FUJI      39 /* (as seen on 400/800) */
 296 #define KEYCODE_INVERSE   39 /* (alternative name; as seen on XL/XE) */
 297
 298 /* N.B. No way to tell left from right Shift keys */
 299
 300
 301 /* Keyboard Space key */
 302
 303 #define KEYCODE_SPACE     33
 304
 305
 306 /* End of _pokey.h */
 307 #endif /* #ifndef __POKEY_H */