diff options
author | Linus Torvalds <torvalds@ppc970.osdl.org> | 2005-04-16 18:20:36 -0400 |
---|---|---|
committer | Linus Torvalds <torvalds@ppc970.osdl.org> | 2005-04-16 18:20:36 -0400 |
commit | 1da177e4c3f41524e886b7f1b8a0c1fc7321cac2 (patch) | |
tree | 0bba044c4ce775e45a88a51686b5d9f90697ea9d /Documentation/sound/alsa/seq_oss.html |
Linux-2.6.12-rc2v2.6.12-rc2
Initial git repository build. I'm not bothering with the full history,
even though we have it. We can create a separate "historical" git
archive of that later if we want to, and in the meantime it's about
3.2GB when imported into git - space that would just make the early
git days unnecessarily complicated, when we don't have a lot of good
infrastructure for it.
Let it rip!
Diffstat (limited to 'Documentation/sound/alsa/seq_oss.html')
-rw-r--r-- | Documentation/sound/alsa/seq_oss.html | 409 |
1 files changed, 409 insertions, 0 deletions
diff --git a/Documentation/sound/alsa/seq_oss.html b/Documentation/sound/alsa/seq_oss.html new file mode 100644 index 000000000000..d9776cf60c07 --- /dev/null +++ b/Documentation/sound/alsa/seq_oss.html | |||
@@ -0,0 +1,409 @@ | |||
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> | ||