| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 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"><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> 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> |
| 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 | 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 | 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); |
| 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 | 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> |
| 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> |
| 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> |