From 849369d6c66d3054688672f97d31fceb8e8230fb Mon Sep 17 00:00:00 2001 From: root Date: Fri, 25 Dec 2015 04:40:36 +0000 Subject: initial_commit --- Documentation/sound/alsa/seq_oss.html | 409 ++++++++++++++++++++++++++++++++++ 1 file changed, 409 insertions(+) create mode 100644 Documentation/sound/alsa/seq_oss.html (limited to 'Documentation/sound/alsa/seq_oss.html') diff --git a/Documentation/sound/alsa/seq_oss.html b/Documentation/sound/alsa/seq_oss.html new file mode 100644 index 00000000..d9776cf6 --- /dev/null +++ b/Documentation/sound/alsa/seq_oss.html @@ -0,0 +1,409 @@ + + + + OSS Sequencer Emulation on ALSA + + + +
+

+ +

+ +
+

+OSS Sequencer Emulation on ALSA

+ +
+

Copyright (c) 1998,1999 by Takashi Iwai +<iwai@ww.uni-erlangen.de> +

ver.0.1.8; Nov. 16, 1999 +

+ +

+ +

+1. Description

+This directory contains the OSS sequencer emulation driver on ALSA. Note +that this program is still in the development state. +

What this does - it provides the emulation of the OSS sequencer, access +via +/dev/sequencer and /dev/music devices. +The most of applications using OSS can run if the appropriate ALSA +sequencer is prepared. +

The following features are emulated by this driver: +

+Furthermore, you can find the following advanced features: + + +

+2. Installation

+Run configure script with both sequencer support (--with-sequencer=yes) +and OSS emulation (--with-oss=yes) options. A module snd-seq-oss.o +will be created. If the synth module of your sound card supports for OSS +emulation (so far, only Emu8000 driver), this module will be loaded automatically. +Otherwise, you need to load this module manually. +

At beginning, this module probes all the MIDI ports which have been +already connected to the sequencer. Once after that, the creation and deletion +of ports are watched by announcement mechanism of ALSA sequencer. +

The available synth and MIDI devices can be found in proc interface. +Run "cat /proc/asound/seq/oss", and check the devices. For example, +if you use an AWE64 card, you'll see like the following: +

        OSS sequencer emulation version 0.1.8
+        ALSA client number 63
+        ALSA receiver port 0
+
+        Number of applications: 0
+
+        Number of synth devices: 1
+
+        synth 0: [EMU8000]
+          type 0x1 : subtype 0x20 : voices 32
+          capabilties : ioctl enabled / load_patch enabled
+
+        Number of MIDI devices: 3
+
+        midi 0: [Emu8000 Port-0] ALSA port 65:0
+          capability write / opened none
+
+        midi 1: [Emu8000 Port-1] ALSA port 65:1
+          capability write / opened none
+
+        midi 2: [0: MPU-401 (UART)] ALSA port 64:0
+          capability read/write / opened none
+Note that the device number may be different from the information of +/proc/asound/oss-devices +or ones of the original OSS driver. Use the device number listed in /proc/asound/seq/oss +to play via OSS sequencer emulation. +

+3. Using Synthesizer Devices

+Run your favorite program. I've tested playmidi-2.4, awemidi-0.4.3, gmod-3.1 +and xmp-1.1.5. You can load samples via /dev/sequencer like sfxload, +too. +

If the lowlevel driver supports multiple access to synth devices (like +Emu8000 driver), two or more applications are allowed to run at the same +time. +

+4. Using MIDI Devices

+So far, only MIDI output was tested. MIDI input was not checked at all, +but hopefully it will work. Use the device number listed in /proc/asound/seq/oss. +Be aware that these numbers are mostly different from the list in +/proc/asound/oss-devices. +

+5. Module Options

+The following module options are available: + + +

+6. Queue Mechanism

+OSS sequencer emulation uses an ALSA priority queue. The +events from /dev/sequencer are processed and put onto the queue +specified by module option. +

All the events from /dev/sequencer are parsed at beginning. +The timing events are also parsed at this moment, so that the events may +be processed in real-time. Sending an event ABSTIME 0 switches the operation +mode to real-time mode, and sending an event RELTIME 0 switches it off. +In the real-time mode, all events are dispatched immediately. +

The queued events are dispatched to the corresponding ALSA sequencer +ports after scheduled time by ALSA sequencer dispatcher. +

If the write-queue is full, the application sleeps until a certain amount +(as default one half) becomes empty in blocking mode. The synchronization +to write timing was implemented, too. +

The input from MIDI devices or echo-back events are stored on read FIFO +queue. If application reads /dev/sequencer in blocking mode, the +process will be awaked. + +

+7. Interface to Synthesizer Device

+ +

+7.1. Registration

+To register an OSS synthesizer device, use snd_seq_oss_synth_register +function. +
int snd_seq_oss_synth_register(char *name, int type, int subtype, int nvoices,
+                              snd_seq_oss_callback_t *oper, void *private_data)
+The arguments name, type, subtype and +nvoices +are used for making the appropriate synth_info structure for ioctl. The +return value is an index number of this device. This index must be remembered +for unregister. If registration is failed, -errno will be returned. +

To release this device, call snd_seq_oss_synth_unregister function: +

int snd_seq_oss_synth_unregister(int index),
+where the index is the index number returned by register function. +

+7.2. Callbacks

+OSS synthesizer devices have capability for sample downloading and ioctls +like sample reset. In OSS emulation, these special features are realized +by using callbacks. The registration argument oper is used to specify these +callbacks. The following callback functions must be defined: +
snd_seq_oss_callback_t:
+        int (*open)(snd_seq_oss_arg_t *p, void *closure);
+        int (*close)(snd_seq_oss_arg_t *p);
+        int (*ioctl)(snd_seq_oss_arg_t *p, unsigned int cmd, unsigned long arg);
+        int (*load_patch)(snd_seq_oss_arg_t *p, int format, const char *buf, int offs, int count);
+        int (*reset)(snd_seq_oss_arg_t *p);
+Except for open and close callbacks, they are allowed
+to be NULL.
+
Each callback function takes the argument type snd_seq_oss_arg_t as the
+first argument.
+
struct snd_seq_oss_arg_t {
+        int app_index;
+        int file_mode;
+        int seq_mode;
+        snd_seq_addr_t addr;
+        void *private_data;
+        int event_passing;
+};

+The first three fields, app_index, file_mode and
+seq_mode
+are initialized by OSS sequencer. The app_index is the application
+index which is unique to each application opening OSS sequencer. The
+file_mode
+is bit-flags indicating the file operation mode. See
+seq_oss.h
+for its meaning. The seq_mode is sequencer operation mode. In
+the current version, only SND_OSSSEQ_MODE_SYNTH is used.
+
The next two fields, addr and private_data, must be
+filled by the synth driver at open callback. The addr contains
+the address of ALSA sequencer port which is assigned to this device. If
+the driver allocates memory for private_data, it must be released
+in close callback by itself.
+
The last field, event_passing, indicates how to translate note-on
+/ off events. In PROCESS_EVENTS mode, the note 255 is regarded
+as velocity change, and key pressure event is passed to the port. In PASS_EVENTS
+mode, all note on/off events are passed to the port without modified. PROCESS_KEYPRESS
+mode checks the note above 128 and regards it as key pressure event (mainly
+for Emu8000 driver).
+

+7.2.1. Open Callback

+The open is called at each time this device is opened by an application
+using OSS sequencer. This must not be NULL. Typically, the open callback
+does the following procedure:
+
    
+
  1. 
+Allocate private data record.
    2. 
+
+
  2. 
+Create an ALSA sequencer port.
    3. 
+
+
  3. 
+Set the new port address on arg->addr.
    4. 
+
+
  4. 
+Set the private data record pointer on arg->private_data.
    5. 
+

+Note that the type bit-flags in port_info of this synth port must NOT contain
+TYPE_MIDI_GENERIC
+bit. Instead, TYPE_SPECIFIC should be used. Also, CAP_SUBSCRIPTION
+bit should NOT be included, too. This is necessary to tell it from other
+normal MIDI devices. If the open procedure succeeded, return zero. Otherwise,
+return -errno.
+

+7.2.2 Ioctl Callback

+The ioctl callback is called when the sequencer receives device-specific
+ioctls. The following two ioctls should be processed by this callback:
+
+The other ioctls are processed inside the sequencer without passing to
+the lowlevel driver.
+

+7.2.3 Load_Patch Callback

+The load_patch callback is used for sample-downloading. This callback
+must read the data on user-space and transfer to each device. Return 0
+if succeeded, and -errno if failed. The format argument is the patch key
+in patch_info record. The buf is user-space pointer where patch_info record
+is stored. The offs can be ignored. The count is total data size of this
+sample data.
+

+7.2.4 Close Callback

+The close callback is called when this device is closed by the
+applicaion. If any private data was allocated in open callback, it must
+be released in the close callback. The deletion of ALSA port should be
+done here, too. This callback must not be NULL.
+

+7.2.5 Reset Callback

+The reset callback is called when sequencer device is reset or
+closed by applications. The callback should turn off the sounds on the
+relevant port immediately, and initialize the status of the port. If this
+callback is undefined, OSS seq sends a HEARTBEAT event to the
+port.
+

+7.3 Events

+Most of the events are processed by sequencer and translated to the adequate
+ALSA sequencer events, so that each synth device can receive by input_event
+callback of ALSA sequencer port. The following ALSA events should be implemented
+by the driver:
+
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
ALSA eventOriginal OSS events
NOTEONSEQ_NOTEON
+
MIDI_NOTEON
NOTESEQ_NOTEOFF
+
MIDI_NOTEOFF
KEYPRESSMIDI_KEY_PRESSURE
CHANPRESSSEQ_AFTERTOUCH
+
MIDI_CHN_PRESSURE
PGMCHANGESEQ_PGMCHANGE
+
MIDI_PGM_CHANGE
PITCHBENDSEQ_CONTROLLER(CTRL_PITCH_BENDER)
+
MIDI_PITCH_BEND
CONTROLLERMIDI_CTL_CHANGE
+
SEQ_BALANCE (with CTL_PAN)
CONTROL14SEQ_CONTROLLER
REGPARAMSEQ_CONTROLLER(CTRL_PITCH_BENDER_RANGE)
SYSEXSEQ_SYSEX

+
+
The most of these behavior can be realized by MIDI emulation driver
+included in the Emu8000 lowlevel driver. In the future release, this module
+will be independent.
+
Some OSS events (SEQ_PRIVATE and SEQ_VOLUME events) are passed as event
+type SND_SEQ_OSS_PRIVATE.  The OSS sequencer passes these event 8 byte
+packets without any modification. The lowlevel driver should process these
+events appropriately.
+

+8. Interface to MIDI Device

+Since the OSS emulation probes the creation and deletion of ALSA MIDI sequencer
+ports automatically by receiving announcement from ALSA sequencer, the
+MIDI devices don't need to be registered explicitly like synth devices.
+However, the MIDI port_info registered to ALSA sequencer must include a group
+name SND_SEQ_GROUP_DEVICE and a capability-bit CAP_READ or
+CAP_WRITE. Also, subscription capabilities, CAP_SUBS_READ or CAP_SUBS_WRITE,
+must be defined, too. If these conditions are not satisfied, the port is not
+registered as OSS sequencer MIDI device.
+
The events via MIDI devices are parsed in OSS sequencer and converted
+to the corresponding ALSA sequencer events. The input from MIDI sequencer
+is also converted to MIDI byte events by OSS sequencer. This works just
+a reverse way of seq_midi module.
+

+9. Known Problems / TODO's

+
+
+
+
+
-- 
cgit v1.2.3