1=============================== 2OSS Sequencer Emulation on ALSA 3=============================== 4 5Copyright (c) 1998,1999 by Takashi Iwai 6 7ver.0.1.8; Nov. 16, 1999 8 9Description 10=========== 11 12This directory contains the OSS sequencer emulation driver on ALSA. Note 13that this program is still in the development state. 14 15What this does - it provides the emulation of the OSS sequencer, access 16via ``/dev/sequencer`` and ``/dev/music`` devices. 17The most of applications using OSS can run if the appropriate ALSA 18sequencer is prepared. 19 20The following features are emulated by this driver: 21 22* Normal sequencer and MIDI events: 23 24 They are converted to the ALSA sequencer events, and sent to the 25 corresponding port. 26 27* Timer events: 28 29 The timer is not selectable by ioctl. The control rate is fixed to 30 100 regardless of HZ. That is, even on Alpha system, a tick is always 31 1/100 second. The base rate and tempo can be changed in ``/dev/music``. 32 33* Patch loading: 34 35 It purely depends on the synth drivers whether it's supported since 36 the patch loading is realized by callback to the synth driver. 37 38* I/O controls: 39 40 Most of controls are accepted. Some controls 41 are dependent on the synth driver, as well as even on original OSS. 42 43Furthermore, you can find the following advanced features: 44 45* Better queue mechanism: 46 47 The events are queued before processing them. 48 49* Multiple applications: 50 51 You can run two or more applications simultaneously (even for OSS 52 sequencer)! 53 However, each MIDI device is exclusive - that is, if a MIDI device 54 is opened once by some application, other applications can't use 55 it. No such a restriction in synth devices. 56 57* Real-time event processing: 58 59 The events can be processed in real time without using out of bound 60 ioctl. To switch to real-time mode, send ABSTIME 0 event. The followed 61 events will be processed in real-time without queued. To switch off the 62 real-time mode, send RELTIME 0 event. 63 64* ``/proc`` interface: 65 66 The status of applications and devices can be shown via 67 ``/proc/asound/seq/oss`` at any time. In the later version, 68 configuration will be changed via ``/proc`` interface, too. 69 70 71Installation 72============ 73 74Run configure script with both sequencer support (``--with-sequencer=yes``) 75and OSS emulation (``--with-oss=yes``) options. A module ``snd-seq-oss.o`` 76will be created. If the synth module of your sound card supports for OSS 77emulation (so far, only Emu8000 driver), this module will be loaded 78automatically. 79Otherwise, you need to load this module manually. 80 81At beginning, this module probes all the MIDI ports which have been 82already connected to the sequencer. Once after that, the creation and deletion 83of ports are watched by announcement mechanism of ALSA sequencer. 84 85The available synth and MIDI devices can be found in proc interface. 86Run ``cat /proc/asound/seq/oss``, and check the devices. For example, 87if you use an AWE64 card, you'll see like the following: 88:: 89 90 OSS sequencer emulation version 0.1.8 91 ALSA client number 63 92 ALSA receiver port 0 93 94 Number of applications: 0 95 96 Number of synth devices: 1 97 synth 0: [EMU8000] 98 type 0x1 : subtype 0x20 : voices 32 99 capabilties : ioctl enabled / load_patch enabled 100 101 Number of MIDI devices: 3 102 midi 0: [Emu8000 Port-0] ALSA port 65:0 103 capability write / opened none 104 105 midi 1: [Emu8000 Port-1] ALSA port 65:1 106 capability write / opened none 107 108 midi 2: [0: MPU-401 (UART)] ALSA port 64:0 109 capability read/write / opened none 110 111Note that the device number may be different from the information of 112``/proc/asound/oss-devices`` or ones of the original OSS driver. 113Use the device number listed in ``/proc/asound/seq/oss`` 114to play via OSS sequencer emulation. 115 116Using Synthesizer Devices 117========================= 118 119Run your favorite program. I've tested playmidi-2.4, awemidi-0.4.3, gmod-3.1 120and xmp-1.1.5. You can load samples via ``/dev/sequencer`` like sfxload, 121too. 122 123If the lowlevel driver supports multiple access to synth devices (like 124Emu8000 driver), two or more applications are allowed to run at the same 125time. 126 127Using MIDI Devices 128================== 129 130So far, only MIDI output was tested. MIDI input was not checked at all, 131but hopefully it will work. Use the device number listed in 132``/proc/asound/seq/oss``. 133Be aware that these numbers are mostly different from the list in 134``/proc/asound/oss-devices``. 135 136Module Options 137============== 138 139The following module options are available: 140 141maxqlen 142 specifies the maximum read/write queue length. This queue is private 143 for OSS sequencer, so that it is independent from the queue length of ALSA 144 sequencer. Default value is 1024. 145 146seq_oss_debug 147 specifies the debug level and accepts zero (= no debug message) or 148 positive integer. Default value is 0. 149 150Queue Mechanism 151=============== 152 153OSS sequencer emulation uses an ALSA priority queue. The 154events from ``/dev/sequencer`` are processed and put onto the queue 155specified by module option. 156 157All the events from ``/dev/sequencer`` are parsed at beginning. 158The timing events are also parsed at this moment, so that the events may 159be processed in real-time. Sending an event ABSTIME 0 switches the operation 160mode to real-time mode, and sending an event RELTIME 0 switches it off. 161In the real-time mode, all events are dispatched immediately. 162 163The queued events are dispatched to the corresponding ALSA sequencer 164ports after scheduled time by ALSA sequencer dispatcher. 165 166If the write-queue is full, the application sleeps until a certain amount 167(as default one half) becomes empty in blocking mode. The synchronization 168to write timing was implemented, too. 169 170The input from MIDI devices or echo-back events are stored on read FIFO 171queue. If application reads ``/dev/sequencer`` in blocking mode, the 172process will be awaked. 173 174Interface to Synthesizer Device 175=============================== 176 177Registration 178------------ 179 180To register an OSS synthesizer device, use snd_seq_oss_synth_register() 181function: 182:: 183 184 int snd_seq_oss_synth_register(char *name, int type, int subtype, int nvoices, 185 snd_seq_oss_callback_t *oper, void *private_data) 186 187The arguments ``name``, ``type``, ``subtype`` and ``nvoices`` 188are used for making the appropriate synth_info structure for ioctl. The 189return value is an index number of this device. This index must be remembered 190for unregister. If registration is failed, -errno will be returned. 191 192To release this device, call snd_seq_oss_synth_unregister() function: 193:: 194 195 int snd_seq_oss_synth_unregister(int index) 196 197where the ``index`` is the index number returned by register function. 198 199Callbacks 200--------- 201 202OSS synthesizer devices have capability for sample downloading and ioctls 203like sample reset. In OSS emulation, these special features are realized 204by using callbacks. The registration argument oper is used to specify these 205callbacks. The following callback functions must be defined: 206:: 207 208 snd_seq_oss_callback_t: 209 int (*open)(snd_seq_oss_arg_t *p, void *closure); 210 int (*close)(snd_seq_oss_arg_t *p); 211 int (*ioctl)(snd_seq_oss_arg_t *p, unsigned int cmd, unsigned long arg); 212 int (*load_patch)(snd_seq_oss_arg_t *p, int format, const char *buf, int offs, int count); 213 int (*reset)(snd_seq_oss_arg_t *p); 214 215Except for ``open`` and ``close`` callbacks, they are allowed to be NULL. 216 217Each callback function takes the argument type ``snd_seq_oss_arg_t`` as the 218first argument. 219:: 220 221 struct snd_seq_oss_arg_t { 222 int app_index; 223 int file_mode; 224 int seq_mode; 225 snd_seq_addr_t addr; 226 void *private_data; 227 int event_passing; 228 }; 229 230The first three fields, ``app_index``, ``file_mode`` and ``seq_mode`` 231are initialized by OSS sequencer. The ``app_index`` is the application 232index which is unique to each application opening OSS sequencer. The 233``file_mode`` is bit-flags indicating the file operation mode. See 234``seq_oss.h`` for its meaning. The ``seq_mode`` is sequencer operation 235mode. In the current version, only ``SND_OSSSEQ_MODE_SYNTH`` is used. 236 237The next two fields, ``addr`` and ``private_data``, must be 238filled by the synth driver at open callback. The ``addr`` contains 239the address of ALSA sequencer port which is assigned to this device. If 240the driver allocates memory for ``private_data``, it must be released 241in close callback by itself. 242 243The last field, ``event_passing``, indicates how to translate note-on 244/ off events. In ``PROCESS_EVENTS`` mode, the note 255 is regarded 245as velocity change, and key pressure event is passed to the port. In 246``PASS_EVENTS`` mode, all note on/off events are passed to the port 247without modified. ``PROCESS_KEYPRESS`` mode checks the note above 128 248and regards it as key pressure event (mainly for Emu8000 driver). 249 250Open Callback 251------------- 252 253The ``open`` is called at each time this device is opened by an application 254using OSS sequencer. This must not be NULL. Typically, the open callback 255does the following procedure: 256 257#. Allocate private data record. 258#. Create an ALSA sequencer port. 259#. Set the new port address on ``arg->addr``. 260#. Set the private data record pointer on ``arg->private_data``. 261 262Note that the type bit-flags in port_info of this synth port must NOT contain 263``TYPE_MIDI_GENERIC`` 264bit. Instead, ``TYPE_SPECIFIC`` should be used. Also, ``CAP_SUBSCRIPTION`` 265bit should NOT be included, too. This is necessary to tell it from other 266normal MIDI devices. If the open procedure succeeded, return zero. Otherwise, 267return -errno. 268 269Ioctl Callback 270-------------- 271 272The ``ioctl`` callback is called when the sequencer receives device-specific 273ioctls. The following two ioctls should be processed by this callback: 274 275IOCTL_SEQ_RESET_SAMPLES 276 reset all samples on memory -- return 0 277 278IOCTL_SYNTH_MEMAVL 279 return the available memory size 280 281FM_4OP_ENABLE 282 can be ignored usually 283 284The other ioctls are processed inside the sequencer without passing to 285the lowlevel driver. 286 287Load_Patch Callback 288------------------- 289 290The ``load_patch`` callback is used for sample-downloading. This callback 291must read the data on user-space and transfer to each device. Return 0 292if succeeded, and -errno if failed. The format argument is the patch key 293in patch_info record. The buf is user-space pointer where patch_info record 294is stored. The offs can be ignored. The count is total data size of this 295sample data. 296 297Close Callback 298-------------- 299 300The ``close`` callback is called when this device is closed by the 301application. If any private data was allocated in open callback, it must 302be released in the close callback. The deletion of ALSA port should be 303done here, too. This callback must not be NULL. 304 305Reset Callback 306-------------- 307 308The ``reset`` callback is called when sequencer device is reset or 309closed by applications. The callback should turn off the sounds on the 310relevant port immediately, and initialize the status of the port. If this 311callback is undefined, OSS seq sends a ``HEARTBEAT`` event to the 312port. 313 314Events 315====== 316 317Most of the events are processed by sequencer and translated to the adequate 318ALSA sequencer events, so that each synth device can receive by input_event 319callback of ALSA sequencer port. The following ALSA events should be 320implemented by the driver: 321 322============= =================== 323ALSA event Original OSS events 324============= =================== 325NOTEON SEQ_NOTEON, MIDI_NOTEON 326NOTE SEQ_NOTEOFF, MIDI_NOTEOFF 327KEYPRESS MIDI_KEY_PRESSURE 328CHANPRESS SEQ_AFTERTOUCH, MIDI_CHN_PRESSURE 329PGMCHANGE SEQ_PGMCHANGE, MIDI_PGM_CHANGE 330PITCHBEND SEQ_CONTROLLER(CTRL_PITCH_BENDER), 331 MIDI_PITCH_BEND 332CONTROLLER MIDI_CTL_CHANGE, 333 SEQ_BALANCE (with CTL_PAN) 334CONTROL14 SEQ_CONTROLLER 335REGPARAM SEQ_CONTROLLER(CTRL_PITCH_BENDER_RANGE) 336SYSEX SEQ_SYSEX 337============= =================== 338 339The most of these behavior can be realized by MIDI emulation driver 340included in the Emu8000 lowlevel driver. In the future release, this module 341will be independent. 342 343Some OSS events (``SEQ_PRIVATE`` and ``SEQ_VOLUME`` events) are passed as event 344type SND_SEQ_OSS_PRIVATE. The OSS sequencer passes these event 8 byte 345packets without any modification. The lowlevel driver should process these 346events appropriately. 347 348Interface to MIDI Device 349======================== 350 351Since the OSS emulation probes the creation and deletion of ALSA MIDI 352sequencer ports automatically by receiving announcement from ALSA 353sequencer, the MIDI devices don't need to be registered explicitly 354like synth devices. 355However, the MIDI port_info registered to ALSA sequencer must include 356a group name ``SND_SEQ_GROUP_DEVICE`` and a capability-bit 357``CAP_READ`` or ``CAP_WRITE``. Also, subscription capabilities, 358``CAP_SUBS_READ`` or ``CAP_SUBS_WRITE``, must be defined, too. If 359these conditions are not satisfied, the port is not registered as OSS 360sequencer MIDI device. 361 362The events via MIDI devices are parsed in OSS sequencer and converted 363to the corresponding ALSA sequencer events. The input from MIDI sequencer 364is also converted to MIDI byte events by OSS sequencer. This works just 365a reverse way of seq_midi module. 366 367Known Problems / TODO's 368======================= 369 370* Patch loading via ALSA instrument layer is not implemented yet. 371 372