From 9ca8dbcc65cfc63d6f5ef3312a33184e1d726e00 Mon Sep 17 00:00:00 2001 From: Yunhong Jiang Date: Tue, 4 Aug 2015 12:17:53 -0700 Subject: Add the rt linux 4.1.3-rt3 as base Import the rt linux 4.1.3-rt3 as OPNFV kvm base. It's from git://git.kernel.org/pub/scm/linux/kernel/git/rt/linux-rt-devel.git linux-4.1.y-rt and the base is: commit 0917f823c59692d751951bf5ea699a2d1e2f26a2 Author: Sebastian Andrzej Siewior Date: Sat Jul 25 12:13:34 2015 +0200 Prepare v4.1.3-rt3 Signed-off-by: Sebastian Andrzej Siewior We lose all the git history this way and it's not good. We should apply another opnfv project repo in future. Change-Id: I87543d81c9df70d99c5001fbdf646b202c19f423 Signed-off-by: Yunhong Jiang --- kernel/Documentation/sound/alsa/seq_oss.html | 409 +++++++++++++++++++++++++++ 1 file changed, 409 insertions(+) create mode 100644 kernel/Documentation/sound/alsa/seq_oss.html (limited to 'kernel/Documentation/sound/alsa/seq_oss.html') diff --git a/kernel/Documentation/sound/alsa/seq_oss.html b/kernel/Documentation/sound/alsa/seq_oss.html new file mode 100644 index 000000000..9663b45f6 --- /dev/null +++ b/kernel/Documentation/sound/alsa/seq_oss.html @@ -0,0 +1,409 @@ + + + + OSS Sequencer Emulation on ALSA + + + + +

+ +

+ + +

+OSS Sequencer Emulation on ALSA

+ +

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: +

+Normal sequencer and MIDI events:

+Timer events:

/dev/music

+Patch loading:

+I/O controls:

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

+Better queue mechanism:

+Multiple applications:

+Real-time event processing:

+/proc interface:

/proc/asound/seq/oss

/proc

+ +

+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: +

+maxqlen

+seq_oss_debug

+ +

+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:
+
+
+Allocate private data record.
+
+
+Create an ALSA sequencer port.
+
+
+Set the new port address on arg->addr.
+
+
+Set the private data record pointer on arg->private_data.
+
+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:
+
+
+IOCTL_SEQ_RESET_SAMPLES
+
+
reset all samples on memory -- return 0
+
+IOCTL_SYNTH_MEMAVL
+
+
return the available memory size
+
+FM_4OP_ENABLE
+
+
can be ignored usually
+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
+application. 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 event Original OSS events
NOTEON SEQ_NOTEON
+
MIDI_NOTEON
NOTE SEQ_NOTEOFF
+
MIDI_NOTEOFF
KEYPRESS MIDI_KEY_PRESSURE
CHANPRESS SEQ_AFTERTOUCH
+
MIDI_CHN_PRESSURE
PGMCHANGE SEQ_PGMCHANGE
+
MIDI_PGM_CHANGE
PITCHBEND SEQ_CONTROLLER(CTRL_PITCH_BENDER)
+
MIDI_PITCH_BEND
CONTROLLER MIDI_CTL_CHANGE
+
SEQ_BALANCE (with CTL_PAN)
CONTROL14 SEQ_CONTROLLER
REGPARAM SEQ_CONTROLLER(CTRL_PITCH_BENDER_RANGE)
SYSEX SEQ_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
+
+
+
+Patch loading via ALSA instrument layer is not implemented yet.
+
+
+
+
-- 
cgit 1.2.3-korg

ALSA event	Original OSS events
NOTEON	SEQ_NOTEON + MIDI_NOTEON
NOTE	SEQ_NOTEOFF + MIDI_NOTEOFF
KEYPRESS	MIDI_KEY_PRESSURE
CHANPRESS	SEQ_AFTERTOUCH + MIDI_CHN_PRESSURE
PGMCHANGE	SEQ_PGMCHANGE + MIDI_PGM_CHANGE
PITCHBEND	SEQ_CONTROLLER(CTRL_PITCH_BENDER) + MIDI_PITCH_BEND
CONTROLLER	MIDI_CTL_CHANGE + SEQ_BALANCE (with CTL_PAN)
CONTROL14	SEQ_CONTROLLER
REGPARAM	SEQ_CONTROLLER(CTRL_PITCH_BENDER_RANGE)
SYSEX	SEQ_SYSEX