include/sound/opl3.h

0001 /* SPDX-License-Identifier: GPL-2.0-or-later */
0002 #ifndef __SOUND_OPL3_H
0003 #define __SOUND_OPL3_H
0004
0005 /*
0006  * Definitions of the OPL-3 registers.
0007  *
0008  * Copyright (c) by Jaroslav Kysela <perex@perex.cz>,
0009  *                  Hannu Savolainen 1993-1996
0010  *
0011  *      The OPL-3 mode is switched on by writing 0x01, to the offset 5
0012  *      of the right side.
0013  *
0014  *      Another special register at the right side is at offset 4. It contains
0015  *      a bit mask defining which voices are used as 4 OP voices.
0016  *
0017  *      The percussive mode is implemented in the left side only.
0018  *
0019  *      With the above exceptions the both sides can be operated independently.
0020  *
0021  *      A 4 OP voice can be created by setting the corresponding
0022  *      bit at offset 4 of the right side.
0023  *
0024  *      For example setting the rightmost bit (0x01) changes the
0025  *      first voice on the right side to the 4 OP mode. The fourth
0026  *      voice is made inaccessible.
0027  *
0028  *      If a voice is set to the 2 OP mode, it works like 2 OP modes
0029  *      of the original YM3812 (AdLib). In addition the voice can
0030  *      be connected the left, right or both stereo channels. It can
0031  *      even be left unconnected. This works with 4 OP voices also.
0032  *
0033  *      The stereo connection bits are located in the FEEDBACK_CONNECTION
0034  *      register of the voice (0xC0-0xC8). In 4 OP voices these bits are
0035  *      in the second half of the voice.
0036  */
0037
0038 #include <sound/core.h>
0039 #include <sound/hwdep.h>
0040 #include <sound/timer.h>
0041 #include <sound/seq_midi_emul.h>
0042 #include <sound/seq_oss.h>
0043 #include <sound/seq_oss_legacy.h>
0044 #include <sound/seq_device.h>
0045 #include <sound/asound_fm.h>
0046
0047 /*
0048  *    Register numbers for the global registers
0049  */
0050
0051 #define OPL3_REG_TEST           0x01
0052 #define   OPL3_ENABLE_WAVE_SELECT   0x20
0053
0054 #define OPL3_REG_TIMER1         0x02
0055 #define OPL3_REG_TIMER2         0x03
0056 #define OPL3_REG_TIMER_CONTROL      0x04    /* Left side */
0057 #define   OPL3_IRQ_RESET        0x80
0058 #define   OPL3_TIMER1_MASK      0x40
0059 #define   OPL3_TIMER2_MASK      0x20
0060 #define   OPL3_TIMER1_START     0x01
0061 #define   OPL3_TIMER2_START     0x02
0062
0063 #define OPL3_REG_CONNECTION_SELECT  0x04    /* Right side */
0064 #define   OPL3_LEFT_4OP_0       0x01
0065 #define   OPL3_LEFT_4OP_1       0x02
0066 #define   OPL3_LEFT_4OP_2       0x04
0067 #define   OPL3_RIGHT_4OP_0      0x08
0068 #define   OPL3_RIGHT_4OP_1      0x10
0069 #define   OPL3_RIGHT_4OP_2      0x20
0070
0071 #define OPL3_REG_MODE           0x05    /* Right side */
0072 #define   OPL3_OPL3_ENABLE      0x01    /* OPL3 mode */
0073 #define   OPL3_OPL4_ENABLE      0x02    /* OPL4 mode */
0074
0075 #define OPL3_REG_KBD_SPLIT      0x08    /* Left side */
0076 #define   OPL3_COMPOSITE_SINE_WAVE_MODE 0x80    /* Don't use with OPL-3? */
0077 #define   OPL3_KEYBOARD_SPLIT       0x40
0078
0079 #define OPL3_REG_PERCUSSION     0xbd    /* Left side only */
0080 #define   OPL3_TREMOLO_DEPTH        0x80
0081 #define   OPL3_VIBRATO_DEPTH        0x40
0082 #define   OPL3_PERCUSSION_ENABLE    0x20
0083 #define   OPL3_BASSDRUM_ON      0x10
0084 #define   OPL3_SNAREDRUM_ON     0x08
0085 #define   OPL3_TOMTOM_ON        0x04
0086 #define   OPL3_CYMBAL_ON        0x02
0087 #define   OPL3_HIHAT_ON         0x01
0088
0089 /*
0090  *    Offsets to the register banks for operators. To get the
0091  *      register number just add the operator offset to the bank offset
0092  *
0093  *      AM/VIB/EG/KSR/Multiple (0x20 to 0x35)
0094  */
0095 #define OPL3_REG_AM_VIB         0x20
0096 #define   OPL3_TREMOLO_ON       0x80
0097 #define   OPL3_VIBRATO_ON       0x40
0098 #define   OPL3_SUSTAIN_ON       0x20
0099 #define   OPL3_KSR          0x10    /* Key scaling rate */
0100 #define   OPL3_MULTIPLE_MASK        0x0f    /* Frequency multiplier */
0101
0102  /*
0103   *   KSL/Total level (0x40 to 0x55)
0104   */
0105 #define OPL3_REG_KSL_LEVEL      0x40
0106 #define   OPL3_KSL_MASK         0xc0    /* Envelope scaling bits */
0107 #define   OPL3_TOTAL_LEVEL_MASK     0x3f    /* Strength (volume) of OP */
0108
0109 /*
0110  *    Attack / Decay rate (0x60 to 0x75)
0111  */
0112 #define OPL3_REG_ATTACK_DECAY       0x60
0113 #define   OPL3_ATTACK_MASK      0xf0
0114 #define   OPL3_DECAY_MASK       0x0f
0115
0116 /*
0117  * Sustain level / Release rate (0x80 to 0x95)
0118  */
0119 #define OPL3_REG_SUSTAIN_RELEASE    0x80
0120 #define   OPL3_SUSTAIN_MASK     0xf0
0121 #define   OPL3_RELEASE_MASK     0x0f
0122
0123 /*
0124  * Wave select (0xE0 to 0xF5)
0125  */
0126 #define OPL3_REG_WAVE_SELECT        0xe0
0127 #define   OPL3_WAVE_SELECT_MASK     0x07
0128
0129 /*
0130  *    Offsets to the register banks for voices. Just add to the
0131  *      voice number to get the register number.
0132  *
0133  *      F-Number low bits (0xA0 to 0xA8).
0134  */
0135 #define OPL3_REG_FNUM_LOW       0xa0
0136
0137 /*
0138  *    F-number high bits / Key on / Block (octave) (0xB0 to 0xB8)
0139  */
0140 #define OPL3_REG_KEYON_BLOCK        0xb0
0141 #define   OPL3_KEYON_BIT        0x20
0142 #define   OPL3_BLOCKNUM_MASK        0x1c
0143 #define   OPL3_FNUM_HIGH_MASK       0x03
0144
0145 /*
0146  *    Feedback / Connection (0xc0 to 0xc8)
0147  *
0148  *      These registers have two new bits when the OPL-3 mode
0149  *      is selected. These bits controls connecting the voice
0150  *      to the stereo channels. For 4 OP voices this bit is
0151  *      defined in the second half of the voice (add 3 to the
0152  *      register offset).
0153  *
0154  *      For 4 OP voices the connection bit is used in the
0155  *      both halves (gives 4 ways to connect the operators).
0156  */
0157 #define OPL3_REG_FEEDBACK_CONNECTION    0xc0
0158 #define   OPL3_FEEDBACK_MASK        0x0e    /* Valid just for 1st OP of a voice */
0159 #define   OPL3_CONNECTION_BIT       0x01
0160 /*
0161  *    In the 4 OP mode there is four possible configurations how the
0162  *      operators can be connected together (in 2 OP modes there is just
0163  *      AM or FM). The 4 OP connection mode is defined by the rightmost
0164  *      bit of the FEEDBACK_CONNECTION (0xC0-0xC8) on the both halves.
0165  *
0166  *      First half      Second half     Mode
0167  *
0168  *                                       +---+
0169  *                                       v   |
0170  *      0               0               >+-1-+--2--3--4-->
0171  *
0172  *
0173  *
0174  *                                       +---+
0175  *                                       |   |
0176  *      0               1               >+-1-+--2-+
0177  *                                                |->
0178  *                                      >--3----4-+
0179  *
0180  *                                       +---+
0181  *                                       |   |
0182  *      1               0               >+-1-+-----+
0183  *                                                 |->
0184  *                                      >--2--3--4-+
0185  *
0186  *                                       +---+
0187  *                                       |   |
0188  *      1               1               >+-1-+--+
0189  *                                              |
0190  *                                      >--2--3-+->
0191  *                                              |
0192  *                                      >--4----+
0193  */
0194 #define   OPL3_STEREO_BITS      0x30    /* OPL-3 only */
0195 #define     OPL3_VOICE_TO_LEFT      0x10
0196 #define     OPL3_VOICE_TO_RIGHT     0x20
0197
0198 /*
0199
0200  */
0201
0202 #define OPL3_LEFT       0x0000
0203 #define OPL3_RIGHT      0x0100
0204
0205 #define OPL3_HW_AUTO        0x0000
0206 #define OPL3_HW_OPL2        0x0200
0207 #define OPL3_HW_OPL3        0x0300
0208 #define OPL3_HW_OPL3_SV     0x0301  /* S3 SonicVibes */
0209 #define OPL3_HW_OPL3_CS     0x0302  /* CS4232/CS4236+ */
0210 #define OPL3_HW_OPL3_FM801  0x0303  /* FM801 */
0211 #define OPL3_HW_OPL3_CS4281 0x0304  /* CS4281 */
0212 #define OPL3_HW_OPL4        0x0400  /* YMF278B/YMF295 */
0213 #define OPL3_HW_OPL4_ML     0x0401  /* YMF704/YMF721 */
0214 #define OPL3_HW_MASK        0xff00
0215
0216 #define MAX_OPL2_VOICES     9
0217 #define MAX_OPL3_VOICES     18
0218
0219 struct snd_opl3;
0220
0221 /*
0222  * Instrument record, aka "Patch"
0223  */
0224
0225 /* FM operator */
0226 struct fm_operator {
0227     unsigned char am_vib;
0228     unsigned char ksl_level;
0229     unsigned char attack_decay;
0230     unsigned char sustain_release;
0231     unsigned char wave_select;
0232 } __attribute__((packed));
0233
0234 /* Instrument data */
0235 struct fm_instrument {
0236     struct fm_operator op[4];
0237     unsigned char feedback_connection[2];
0238     unsigned char echo_delay;
0239     unsigned char echo_atten;
0240     unsigned char chorus_spread;
0241     unsigned char trnsps;
0242     unsigned char fix_dur;
0243     unsigned char modes;
0244     unsigned char fix_key;
0245 };
0246
0247 /* type */
0248 #define FM_PATCH_OPL2   0x01        /* OPL2 2 operators FM instrument */
0249 #define FM_PATCH_OPL3   0x02        /* OPL3 4 operators FM instrument */
0250
0251 /* Instrument record */
0252 struct fm_patch {
0253     unsigned char prog;
0254     unsigned char bank;
0255     unsigned char type;
0256     struct fm_instrument inst;
0257     char name[24];
0258     struct fm_patch *next;
0259 };
0260
0261
0262 /*
0263  * A structure to keep track of each hardware voice
0264  */
0265 struct snd_opl3_voice {
0266     int  state;     /* status */
0267 #define SNDRV_OPL3_ST_OFF       0   /* Not playing */
0268 #define SNDRV_OPL3_ST_ON_2OP    1   /* 2op voice is allocated */
0269 #define SNDRV_OPL3_ST_ON_4OP    2   /* 4op voice is allocated */
0270 #define SNDRV_OPL3_ST_NOT_AVAIL -1  /* voice is not available */
0271
0272     unsigned int time;  /* An allocation time */
0273     unsigned char note; /* Note currently assigned to this voice */
0274
0275     unsigned long note_off; /* note-off time */
0276     int note_off_check; /* check note-off time */
0277
0278     unsigned char keyon_reg;    /* KON register shadow */
0279
0280     struct snd_midi_channel *chan;  /* Midi channel for this note */
0281 };
0282
0283 struct snd_opl3 {
0284     unsigned long l_port;
0285     unsigned long r_port;
0286     struct resource *res_l_port;
0287     struct resource *res_r_port;
0288     unsigned short hardware;
0289     /* hardware access */
0290     void (*command) (struct snd_opl3 * opl3, unsigned short cmd, unsigned char val);
0291     unsigned short timer_enable;
0292     int seq_dev_num;    /* sequencer device number */
0293     struct snd_timer *timer1;
0294     struct snd_timer *timer2;
0295     spinlock_t timer_lock;
0296
0297     void *private_data;
0298     void (*private_free)(struct snd_opl3 *);
0299
0300     struct snd_hwdep *hwdep;
0301     spinlock_t reg_lock;
0302     struct snd_card *card;      /* The card that this belongs to */
0303     unsigned char fm_mode;      /* OPL mode, see SNDRV_DM_FM_MODE_XXX */
0304     unsigned char rhythm;       /* percussion mode flag */
0305     unsigned char max_voices;   /* max number of voices */
0306 #if IS_ENABLED(CONFIG_SND_SEQUENCER)
0307 #define SNDRV_OPL3_MODE_SYNTH 0     /* OSS - voices allocated by application */
0308 #define SNDRV_OPL3_MODE_SEQ 1       /* ALSA - driver handles voice allocation */
0309     int synth_mode;         /* synth mode */
0310     int seq_client;
0311
0312     struct snd_seq_device *seq_dev; /* sequencer device */
0313     struct snd_midi_channel_set * chset;
0314
0315 #if IS_ENABLED(CONFIG_SND_SEQUENCER_OSS)
0316     struct snd_seq_device *oss_seq_dev; /* OSS sequencer device */
0317     struct snd_midi_channel_set * oss_chset;
0318 #endif
0319
0320 #define OPL3_PATCH_HASH_SIZE    32
0321     struct fm_patch *patch_table[OPL3_PATCH_HASH_SIZE];
0322
0323     struct snd_opl3_voice voices[MAX_OPL3_VOICES]; /* Voices (OPL3 'channel') */
0324     int use_time;           /* allocation counter */
0325
0326     unsigned short connection_reg;  /* connection reg shadow */
0327     unsigned char drum_reg;     /* percussion reg shadow */
0328
0329     spinlock_t voice_lock;      /* Lock for voice access */
0330
0331     struct timer_list tlist;    /* timer for note-offs and effects */
0332     int sys_timer_status;       /* system timer run status */
0333     spinlock_t sys_timer_lock;  /* Lock for system timer access */
0334 #endif
0335 };
0336
0337 /* opl3.c */
0338 void snd_opl3_interrupt(struct snd_hwdep * hw);
0339 int snd_opl3_new(struct snd_card *card, unsigned short hardware,
0340          struct snd_opl3 **ropl3);
0341 int snd_opl3_init(struct snd_opl3 *opl3);
0342 int snd_opl3_create(struct snd_card *card,
0343             unsigned long l_port, unsigned long r_port,
0344             unsigned short hardware,
0345             int integrated,
0346             struct snd_opl3 ** opl3);
0347 int snd_opl3_timer_new(struct snd_opl3 * opl3, int timer1_dev, int timer2_dev);
0348 int snd_opl3_hwdep_new(struct snd_opl3 * opl3, int device, int seq_device,
0349                struct snd_hwdep ** rhwdep);
0350
0351 /* opl3_synth */
0352 int snd_opl3_open(struct snd_hwdep * hw, struct file *file);
0353 int snd_opl3_ioctl(struct snd_hwdep * hw, struct file *file,
0354            unsigned int cmd, unsigned long arg);
0355 int snd_opl3_release(struct snd_hwdep * hw, struct file *file);
0356
0357 void snd_opl3_reset(struct snd_opl3 * opl3);
0358
0359 #if IS_ENABLED(CONFIG_SND_SEQUENCER)
0360 long snd_opl3_write(struct snd_hwdep *hw, const char __user *buf, long count,
0361             loff_t *offset);
0362 int snd_opl3_load_patch(struct snd_opl3 *opl3,
0363             int prog, int bank, int type,
0364             const char *name,
0365             const unsigned char *ext,
0366             const unsigned char *data);
0367 struct fm_patch *snd_opl3_find_patch(struct snd_opl3 *opl3, int prog, int bank,
0368                      int create_patch);
0369 void snd_opl3_clear_patches(struct snd_opl3 *opl3);
0370 #else
0371 #define snd_opl3_write  NULL
0372 static inline void snd_opl3_clear_patches(struct snd_opl3 *opl3) {}
0373 #endif
0374
0375 #endif /* __SOUND_OPL3_H */