Documentation/sound/alsa/seq_oss.html

   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>
  15 OSS 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">&lt;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>
  26 1. Description</H2>
  27 This directory contains the OSS sequencer emulation driver on ALSA. Note
  28 that this program is still in the development state.
  29 <P>What this does - it provides the emulation of the OSS sequencer, access
  30 via
  31 <TT>/dev/sequencer</TT> and <TT>/dev/music</TT> devices.
  32 The most of applications using OSS can run if the appropriate ALSA
  33 sequencer is prepared.
  34 <P>The following features are emulated by this driver:
  35 <UL>
  36 <LI>
  37 Normal sequencer and MIDI events:</LI>
  38
  39 <BR>They are converted to the ALSA sequencer events, and sent to the corresponding
  40 port.
  41 <LI>
  42 Timer events:</LI>
  43
  44 <BR>The timer is not selectable by ioctl. The control rate is fixed to
  45 100 regardless of HZ. That is, even on Alpha system, a tick is always
  46 1/100 second. The base rate and tempo can be changed in <TT>/dev/music</TT>.
  47
  48 <LI>
  49 Patch loading:</LI>
  50
  51 <BR>It purely depends on the synth drivers whether it's supported since
  52 the patch loading is realized by callback to the synth driver.
  53 <LI>
  54 I/O controls:</LI>
  55
  56 <BR>Most of controls are accepted. Some controls
  57 are dependent on the synth driver, as well as even on original OSS.</UL>
  58 Furthermore, you can find the following advanced features:
  59 <UL>
  60 <LI>
  61 Better queue mechanism:</LI>
  62
  63 <BR>The events are queued before processing them.
  64 <LI>
  65 Multiple applications:</LI>
  66
  67 <BR>You can run two or more applications simultaneously (even for OSS sequencer)!
  68 However, each MIDI device is exclusive - that is, if a MIDI device is opened
  69 once by some application, other applications can't use it. No such a restriction
  70 in synth devices.
  71 <LI>
  72 Real-time event processing:</LI>
  73
  74 <BR>The events can be processed in real time without using out of bound
  75 ioctl. To switch to real-time mode, send ABSTIME 0 event. The followed
  76 events will be processed in real-time without queued. To switch off the
  77 real-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>
  82 at any time. In the later version, configuration will be changed via <TT>/proc</TT>
  83 interface, too.</UL>
  84
  85 <H2>
  86 2. Installation</H2>
  87 Run configure script with both sequencer support (<TT>--with-sequencer=yes</TT>)
  88 and OSS emulation (<TT>--with-oss=yes</TT>) options. A module <TT>snd-seq-oss.o</TT>
  89 will be created. If the synth module of your sound card supports for OSS
  90 emulation (so far, only Emu8000 driver), this module will be loaded automatically.
  91 Otherwise, you need to load this module manually.
  92 <P>At beginning, this module probes all the MIDI ports which have been
  93 already connected to the sequencer. Once after that, the creation and deletion
  94 of ports are watched by announcement mechanism of ALSA sequencer.
  95 <P>The available synth and MIDI devices can be found in proc interface.
  96 Run "<TT>cat /proc/asound/seq/oss</TT>", and check the devices. For example,
  97 if you use an AWE64 card, you'll see like the following:
  98 <PRE>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; OSS sequencer emulation version 0.1.8
  99 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ALSA client number 63
 100 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ALSA receiver port 0
 101
 102 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Number of applications: 0
 103
 104 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Number of synth devices: 1
 105
 106 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; synth 0: [EMU8000]
 107 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; type 0x1 : subtype 0x20 : voices 32
 108 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; capabilties : ioctl enabled / load_patch enabled
 109
 110 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Number of MIDI devices: 3
 111
 112 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; midi 0: [Emu8000 Port-0] ALSA port 65:0
 113 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; capability write / opened none
 114
 115 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; midi 1: [Emu8000 Port-1] ALSA port 65:1
 116 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; capability write / opened none
 117
 118 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; midi 2: [0: MPU-401 (UART)] ALSA port 64:0
 119 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; capability read/write / opened none</PRE>
 120 Note that the device number may be different from the information of
 121 <TT>/proc/asound/oss-devices</TT>
 122 or ones of the original OSS driver. Use the device number listed in <TT>/proc/asound/seq/oss</TT>
 123 to play via OSS sequencer emulation.
 124 <H2>
 125 3. Using Synthesizer Devices</H2>
 126 Run your favorite program. I've tested playmidi-2.4, awemidi-0.4.3, gmod-3.1
 127 and xmp-1.1.5. You can load samples via <TT>/dev/sequencer</TT> like sfxload,
 128 too.
 129 <P>If the lowlevel driver supports multiple access to synth devices (like
 130 Emu8000 driver), two or more applications are allowed to run at the same
 131 time.
 132 <H2>
 133 4. Using MIDI Devices</H2>
 134 So far, only MIDI output was tested. MIDI input was not checked at all,
 135 but hopefully it will work. Use the device number listed in <TT>/proc/asound/seq/oss</TT>.
 136 Be aware that these numbers are mostly different from the list in
 137 <TT>/proc/asound/oss-devices</TT>.
 138 <H2>
 139 5. Module Options</H2>
 140 The 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
 146 for OSS sequencer, so that it is independent from the queue length of ALSA
 147 sequencer. 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
 152 positive integer. Default value is 0.</UL>
 153
 154 <H2>
 155 6. Queue Mechanism</H2>
 156 OSS sequencer emulation uses an ALSA priority queue. The
 157 events from <TT>/dev/sequencer</TT> are processed and put onto the queue
 158 specified by module option.
 159 <P>All the events from <TT>/dev/sequencer</TT> are parsed at beginning.
 160 The timing events are also parsed at this moment, so that the events may
 161 be processed in real-time. Sending an event ABSTIME 0 switches the operation
 162 mode to real-time mode, and sending an event RELTIME 0 switches it off.
 163 In the real-time mode, all events are dispatched immediately.
 164 <P>The queued events are dispatched to the corresponding ALSA sequencer
 165 ports 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
 168 to write timing was implemented, too.
 169 <P>The input from MIDI devices or echo-back events are stored on read FIFO
 170 queue. If application reads <TT>/dev/sequencer</TT> in blocking mode, the
 171 process will be awaked.
 172
 173 <H2>
 174 7. Interface to Synthesizer Device</H2>
 175
 176 <H3>
 177 7.1. Registration</H3>
 178 To register an OSS synthesizer device, use <TT>snd_seq_oss_synth_register</TT>
 179 function.
 180 <PRE>int snd_seq_oss_synth_register(char *name, int type, int subtype, int nvoices,
 181 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; snd_seq_oss_callback_t *oper, void *private_data)</PRE>
 182 The arguments <TT>name</TT>, <TT>type</TT>, <TT>subtype</TT> and
 183 <TT>nvoices</TT>
 184 are used for making the appropriate synth_info structure for ioctl. The
 185 return value is an index number of this device. This index must be remembered
 186 for 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>
 189 where the <TT>index</TT> is the index number returned by register function.
 190 <H3>
 191 7.2. Callbacks</H3>
 192 OSS synthesizer devices have capability for sample downloading and ioctls
 193 like sample reset. In OSS emulation, these special features are realized
 194 by using callbacks. The registration argument oper is used to specify these
 195 callbacks. The following callback functions must be defined:
 196 <PRE>snd_seq_oss_callback_t:
 197 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int (*open)(snd_seq_oss_arg_t *p, void *closure);
 198 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int (*close)(snd_seq_oss_arg_t *p);
 199 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int (*ioctl)(snd_seq_oss_arg_t *p, unsigned int cmd, unsigned long arg);
 200 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int (*load_patch)(snd_seq_oss_arg_t *p, int format, const char *buf, int offs, int count);
 201 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int (*reset)(snd_seq_oss_arg_t *p);
 202 Except for <TT>open</TT> and <TT>close</TT> callbacks, they are allowed
 203 to be NULL.
 204 <P>Each callback function takes the argument type snd_seq_oss_arg_t as the
 205 first argument.
 206 <PRE>struct snd_seq_oss_arg_t {
 207 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int app_index;
 208 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int file_mode;
 209 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int seq_mode;
 210 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; snd_seq_addr_t addr;
 211 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; void *private_data;
 212 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int event_passing;
 213 };</PRE>
 214 The first three fields, <TT>app_index</TT>, <TT>file_mode</TT> and
 215 <TT>seq_mode</TT>
 216 are initialized by OSS sequencer. The <TT>app_index</TT> is the application
 217 index which is unique to each application opening OSS sequencer. The
 218 <TT>file_mode</TT>
 219 is bit-flags indicating the file operation mode. See
 220 <TT>seq_oss.h</TT>
 221 for its meaning. The <TT>seq_mode</TT> is sequencer operation mode. In
 222 the 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
 224 filled by the synth driver at open callback. The <TT>addr</TT> contains
 225 the address of ALSA sequencer port which is assigned to this device. If
 226 the driver allocates memory for <TT>private_data</TT>, it must be released
 227 in 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
 230 as velocity change, and key pressure event is passed to the port. In <TT>PASS_EVENTS</TT>
 231 mode, all note on/off events are passed to the port without modified. <TT>PROCESS_KEYPRESS</TT>
 232 mode checks the note above 128 and regards it as key pressure event (mainly
 233 for Emu8000 driver).
 234 <H4>
 235 7.2.1. Open Callback</H4>
 236 The <TT>open</TT> is called at each time this device is opened by an application
 237 using OSS sequencer. This must not be NULL. Typically, the open callback
 238 does the following procedure:
 239 <OL>
 240 <LI>
 241 Allocate private data record.</LI>
 242
 243 <LI>
 244 Create an ALSA sequencer port.</LI>
 245
 246 <LI>
 247 Set the new port address on arg->addr.</LI>
 248
 249 <LI>
 250 Set the private data record pointer on arg->private_data.</LI>
 251 </OL>
 252 Note that the type bit-flags in port_info of this synth port must NOT contain
 253 <TT>TYPE_MIDI_GENERIC</TT>
 254 bit. Instead, <TT>TYPE_SPECIFIC</TT> should be used. Also, <TT>CAP_SUBSCRIPTION</TT>
 255 bit should NOT be included, too. This is necessary to tell it from other
 256 normal MIDI devices. If the open procedure succeeded, return zero. Otherwise,
 257 return -errno.
 258 <H4>
 259 7.2.2 Ioctl Callback</H4>
 260 The <TT>ioctl</TT> callback is called when the sequencer receives device-specific
 261 ioctls. 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>
 275 The other ioctls are processed inside the sequencer without passing to
 276 the lowlevel driver.
 277 <H4>
 278 7.2.3 Load_Patch Callback</H4>
 279 The <TT>load_patch</TT> callback is used for sample-downloading. This callback
 280 must read the data on user-space and transfer to each device. Return 0
 281 if succeeded, and -errno if failed. The format argument is the patch key
 282 in patch_info record. The buf is user-space pointer where patch_info record
 283 is stored. The offs can be ignored. The count is total data size of this
 284 sample data.
 285 <H4>
 286 7.2.4 Close Callback</H4>
 287 The <TT>close</TT> callback is called when this device is closed by the
 288 applicaion. If any private data was allocated in open callback, it must
 289 be released in the close callback. The deletion of ALSA port should be
 290 done here, too. This callback must not be NULL.
 291 <H4>
 292 7.2.5 Reset Callback</H4>
 293 The <TT>reset</TT> callback is called when sequencer device is reset or
 294 closed by applications. The callback should turn off the sounds on the
 295 relevant port immediately, and initialize the status of the port. If this
 296 callback is undefined, OSS seq sends a <TT>HEARTBEAT</TT> event to the
 297 port.
 298 <H3>
 299 7.3 Events</H3>
 300 Most of the events are processed by sequencer and translated to the adequate
 301 ALSA sequencer events, so that each synth device can receive by input_event
 302 callback of ALSA sequencer port. The following ALSA events should be implemented
 303 by the driver:
 304 <BR>&nbsp;
 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
 380 included in the Emu8000 lowlevel driver. In the future release, this module
 381 will be independent.
 382 <P>Some OSS events (<TT>SEQ_PRIVATE</TT> and <TT>SEQ_VOLUME</TT> events) are passed as event
 383 type SND_SEQ_OSS_PRIVATE.  The OSS sequencer passes these event 8 byte
 384 packets without any modification. The lowlevel driver should process these
 385 events appropriately.
 386 <H2>
 387 8. Interface to MIDI Device</H2>
 388 Since the OSS emulation probes the creation and deletion of ALSA MIDI sequencer
 389 ports automatically by receiving announcement from ALSA sequencer, the
 390 MIDI devices don't need to be registered explicitly like synth devices.
 391 However, the MIDI port_info registered to ALSA sequencer must include a group
 392 name <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>,
 394 must be defined, too. If these conditions are not satisfied, the port is not
 395 registered as OSS sequencer MIDI device.
 396 <P>The events via MIDI devices are parsed in OSS sequencer and converted
 397 to the corresponding ALSA sequencer events. The input from MIDI sequencer
 398 is also converted to MIDI byte events by OSS sequencer. This works just
 399 a reverse way of seq_midi module.
 400 <H2>
 401 9. Known Problems / TODO's</H2>
 402
 403 <UL>
 404 <LI>
 405 Patch loading via ALSA instrument layer is not implemented yet.</LI>
 406 </UL>
 407
 408 </BODY>
 409 </HTML>