1 ===============================
2 OSS Sequencer Emulation on ALSA
3 ===============================
4
5 Copyright (c) 1998,1999 by Takashi Iwai
6
7 ver.0.1.8; Nov. 16, 1999
8
9 Description
10 ===========
11
12 This directory contains the OSS sequencer emul
13 that this program is still in the development
14
15 What this does - it provides the emulation of
16 via ``/dev/sequencer`` and ``/dev/music`` devi
17 The most of applications using OSS can run if
18 sequencer is prepared.
19
20 The following features are emulated by this dr
21
22 * Normal sequencer and MIDI events:
23
24 They are converted to the ALSA sequencer e
25 corresponding port.
26
27 * Timer events:
28
29 The timer is not selectable by ioctl. The
30 100 regardless of HZ. That is, even on Alp
31 1/100 second. The base rate and tempo can
32
33 * Patch loading:
34
35 It purely depends on the synth drivers whe
36 the patch loading is realized by callback
37
38 * I/O controls:
39
40 Most of controls are accepted. Some contro
41 are dependent on the synth driver, as well
42
43 Furthermore, you can find the following advanc
44
45 * Better queue mechanism:
46
47 The events are queued before processing th
48
49 * Multiple applications:
50
51 You can run two or more applications simul
52 sequencer)!
53 However, each MIDI device is exclusive - t
54 is opened once by some application, other
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 w
60 ioctl. To switch to real-time mode, send A
61 events will be processed in real-time with
62 real-time mode, send RELTIME 0 event.
63
64 * ``/proc`` interface:
65
66 The status of applications and devices can
67 ``/proc/asound/seq/oss`` at any time. In t
68 configuration will be changed via ``/proc`
69
70
71 Installation
72 ============
73
74 Run configure script with both sequencer suppo
75 and OSS emulation (``--with-oss=yes``) options
76 will be created. If the synth module of your s
77 emulation (so far, only Emu8000 driver), this
78 automatically.
79 Otherwise, you need to load this module manual
80
81 At beginning, this module probes all the MIDI
82 already connected to the sequencer. Once after
83 of ports are watched by announcement mechanism
84
85 The available synth and MIDI devices can be fo
86 Run ``cat /proc/asound/seq/oss``, and check th
87 if you use an AWE64 card, you'll see like the
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 capabilities : ioctl enabled / load_patc
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
111 Note that the device number may be different f
112 ``/proc/asound/oss-devices`` or ones of the or
113 Use the device number listed in ``/proc/asound
114 to play via OSS sequencer emulation.
115
116 Using Synthesizer Devices
117 =========================
118
119 Run your favorite program. I've tested playmid
120 and xmp-1.1.5. You can load samples via ``/dev
121 too.
122
123 If the lowlevel driver supports multiple acces
124 Emu8000 driver), two or more applications are
125 time.
126
127 Using MIDI Devices
128 ==================
129
130 So far, only MIDI output was tested. MIDI inpu
131 but hopefully it will work. Use the device num
132 ``/proc/asound/seq/oss``.
133 Be aware that these numbers are mostly differe
134 ``/proc/asound/oss-devices``.
135
136 Module Options
137 ==============
138
139 The following module options are available:
140
141 maxqlen
142 specifies the maximum read/write queue lengt
143 for OSS sequencer, so that it is independent
144 sequencer. Default value is 1024.
145
146 seq_oss_debug
147 specifies the debug level and accepts zero (
148 positive integer. Default value is 0.
149
150 Queue Mechanism
151 ===============
152
153 OSS sequencer emulation uses an ALSA priority
154 events from ``/dev/sequencer`` are processed a
155 specified by module option.
156
157 All the events from ``/dev/sequencer`` are par
158 The timing events are also parsed at this mome
159 be processed in real-time. Sending an event AB
160 mode to real-time mode, and sending an event R
161 In the real-time mode, all events are dispatch
162
163 The queued events are dispatched to the corres
164 ports after scheduled time by ALSA sequencer d
165
166 If the write-queue is full, the application sl
167 (as default one half) becomes empty in blockin
168 to write timing was implemented, too.
169
170 The input from MIDI devices or echo-back event
171 queue. If application reads ``/dev/sequencer``
172 process will be awaked.
173
174 Interface to Synthesizer Device
175 ===============================
176
177 Registration
178 ------------
179
180 To register an OSS synthesizer device, use snd
181 function:
182 ::
183
184 int snd_seq_oss_synth_register(char *name, i
185 snd_seq_oss_callback_t *oper, void *
186
187 The arguments ``name``, ``type``, ``subtype``
188 are used for making the appropriate synth_info
189 return value is an index number of this device
190 for unregister. If registration is failed, -er
191
192 To release this device, call snd_seq_oss_synth
193 ::
194
195 int snd_seq_oss_synth_unregister(int index)
196
197 where the ``index`` is the index number return
198
199 Callbacks
200 ---------
201
202 OSS synthesizer devices have capability for sa
203 like sample reset. In OSS emulation, these spe
204 by using callbacks. The registration argument
205 callbacks. The following callback functions mu
206 ::
207
208 snd_seq_oss_callback_t:
209 int (*open)(snd_seq_oss_arg_t *p, void *clo
210 int (*close)(snd_seq_oss_arg_t *p);
211 int (*ioctl)(snd_seq_oss_arg_t *p, unsigned
212 int (*load_patch)(snd_seq_oss_arg_t *p, int
213 int (*reset)(snd_seq_oss_arg_t *p);
214
215 Except for ``open`` and ``close`` callbacks, t
216
217 Each callback function takes the argument type
218 first 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
230 The first three fields, ``app_index``, ``file_
231 are initialized by OSS sequencer. The ``app_in
232 index which is unique to each application open
233 ``file_mode`` is bit-flags indicating the file
234 ``seq_oss.h`` for its meaning. The ``seq_mode`
235 mode. In the current version, only ``SND_OSSSE
236
237 The next two fields, ``addr`` and ``private_da
238 filled by the synth driver at open callback. T
239 the address of ALSA sequencer port which is as
240 the driver allocates memory for ``private_data
241 in close callback by itself.
242
243 The last field, ``event_passing``, indicates h
244 / off events. In ``PROCESS_EVENTS`` mode, the
245 as velocity change, and key pressure event is
246 ``PASS_EVENTS`` mode, all note on/off events a
247 without modified. ``PROCESS_KEYPRESS`` mode ch
248 and regards it as key pressure event (mainly f
249
250 Open Callback
251 -------------
252
253 The ``open`` is called at each time this devic
254 using OSS sequencer. This must not be NULL. Ty
255 does 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 ``ar
261
262 Note that the type bit-flags in port_info of t
263 ``TYPE_MIDI_GENERIC``
264 bit. Instead, ``TYPE_SPECIFIC`` should be used
265 bit should NOT be included, too. This is neces
266 normal MIDI devices. If the open procedure suc
267 return -errno.
268
269 Ioctl Callback
270 --------------
271
272 The ``ioctl`` callback is called when the sequ
273 ioctls. The following two ioctls should be pro
274
275 IOCTL_SEQ_RESET_SAMPLES
276 reset all samples on memory -- return 0
277
278 IOCTL_SYNTH_MEMAVL
279 return the available memory size
280
281 FM_4OP_ENABLE
282 can be ignored usually
283
284 The other ioctls are processed inside the sequ
285 the lowlevel driver.
286
287 Load_Patch Callback
288 -------------------
289
290 The ``load_patch`` callback is used for sample
291 must read the data on user-space and transfer
292 if succeeded, and -errno if failed. The format
293 in patch_info record. The buf is user-space po
294 is stored. The offs can be ignored. The count
295 sample data.
296
297 Close Callback
298 --------------
299
300 The ``close`` callback is called when this dev
301 application. If any private data was allocated
302 be released in the close callback. The deletio
303 done here, too. This callback must not be NULL
304
305 Reset Callback
306 --------------
307
308 The ``reset`` callback is called when sequence
309 closed by applications. The callback should tu
310 relevant port immediately, and initialize the
311 callback is undefined, OSS seq sends a ``HEART
312 port.
313
314 Events
315 ======
316
317 Most of the events are processed by sequencer
318 ALSA sequencer events, so that each synth devi
319 callback of ALSA sequencer port. The following
320 implemented by the driver:
321
322 ============= ===================
323 ALSA event Original OSS events
324 ============= ===================
325 NOTEON SEQ_NOTEON, MIDI_NOTEON
326 NOTE SEQ_NOTEOFF, MIDI_NOTEOFF
327 KEYPRESS MIDI_KEY_PRESSURE
328 CHANPRESS SEQ_AFTERTOUCH, MIDI_CHN_PRESS
329 PGMCHANGE SEQ_PGMCHANGE, MIDI_PGM_CHANGE
330 PITCHBEND SEQ_CONTROLLER(CTRL_PITCH_BEND
331 MIDI_PITCH_BEND
332 CONTROLLER MIDI_CTL_CHANGE,
333 SEQ_BALANCE (with CTL_PAN)
334 CONTROL14 SEQ_CONTROLLER
335 REGPARAM SEQ_CONTROLLER(CTRL_PITCH_BEND
336 SYSEX SEQ_SYSEX
337 ============= ===================
338
339 The most of these behavior can be realized by
340 included in the Emu8000 lowlevel driver. In th
341 will be independent.
342
343 Some OSS events (``SEQ_PRIVATE`` and ``SEQ_VOL
344 type SND_SEQ_OSS_PRIVATE. The OSS sequencer p
345 packets without any modification. The lowlevel
346 events appropriately.
347
348 Interface to MIDI Device
349 ========================
350
351 Since the OSS emulation probes the creation an
352 sequencer ports automatically by receiving ann
353 sequencer, the MIDI devices don't need to be r
354 like synth devices.
355 However, the MIDI port_info registered to ALSA
356 a group name ``SND_SEQ_GROUP_DEVICE`` and a ca
357 ``CAP_READ`` or ``CAP_WRITE``. Also, subscript
358 ``CAP_SUBS_READ`` or ``CAP_SUBS_WRITE``, must
359 these conditions are not satisfied, the port i
360 sequencer MIDI device.
361
362 The events via MIDI devices are parsed in OSS
363 to the corresponding ALSA sequencer events. Th
364 is also converted to MIDI byte events by OSS s
365 a reverse way of seq_midi module.
366
367 Known Problems / TODO's
368 =======================
369
370 * Patch loading via ALSA instrument layer is n
371
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.