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