summaryrefslogtreecommitdiff
path: root/Documentation/sound
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/sound')
-rw-r--r--Documentation/sound/cards/audigy-mixer.rst38
-rw-r--r--Documentation/sound/cards/index.rst1
-rw-r--r--Documentation/sound/cards/pcmtest.rst120
-rw-r--r--Documentation/sound/cards/sb-live-mixer.rst2
-rw-r--r--Documentation/sound/designs/compress-offload.rst11
-rw-r--r--Documentation/sound/designs/index.rst1
-rw-r--r--Documentation/sound/designs/midi-2.0.rst378
7 files changed, 526 insertions, 25 deletions
diff --git a/Documentation/sound/cards/audigy-mixer.rst b/Documentation/sound/cards/audigy-mixer.rst
index aa176451d5b5..ea66b50a2b03 100644
--- a/Documentation/sound/cards/audigy-mixer.rst
+++ b/Documentation/sound/cards/audigy-mixer.rst
@@ -227,7 +227,7 @@ PCM stream related controls
name='EMU10K1 PCM Volume',index 0-31
------------------------------------
-Channel volume attenuation in range 0-0xffff. The maximum value (no
+Channel volume attenuation in range 0-0x1fffd. The middle value (no
attenuation) is default. The channel mapping for three values is
as follows:
@@ -240,30 +240,30 @@ name='EMU10K1 PCM Send Routing',index 0-31
This control specifies the destination - FX-bus accumulators. There are 24
values in this mapping:
-* 0 - mono, A destination (FX-bus 0-63), default 0
-* 1 - mono, B destination (FX-bus 0-63), default 1
-* 2 - mono, C destination (FX-bus 0-63), default 2
-* 3 - mono, D destination (FX-bus 0-63), default 3
-* 4 - mono, E destination (FX-bus 0-63), default 0
-* 5 - mono, F destination (FX-bus 0-63), default 0
-* 6 - mono, G destination (FX-bus 0-63), default 0
-* 7 - mono, H destination (FX-bus 0-63), default 0
-* 8 - left, A destination (FX-bus 0-63), default 0
-* 9 - left, B destination (FX-bus 0-63), default 1
+* 0 - mono, A destination (FX-bus 0-63), default 0
+* 1 - mono, B destination (FX-bus 0-63), default 1
+* 2 - mono, C destination (FX-bus 0-63), default 2
+* 3 - mono, D destination (FX-bus 0-63), default 3
+* 4 - mono, E destination (FX-bus 0-63), default 4
+* 5 - mono, F destination (FX-bus 0-63), default 5
+* 6 - mono, G destination (FX-bus 0-63), default 6
+* 7 - mono, H destination (FX-bus 0-63), default 7
+* 8 - left, A destination (FX-bus 0-63), default 0
+* 9 - left, B destination (FX-bus 0-63), default 1
* 10 - left, C destination (FX-bus 0-63), default 2
* 11 - left, D destination (FX-bus 0-63), default 3
-* 12 - left, E destination (FX-bus 0-63), default 0
-* 13 - left, F destination (FX-bus 0-63), default 0
-* 14 - left, G destination (FX-bus 0-63), default 0
-* 15 - left, H destination (FX-bus 0-63), default 0
+* 12 - left, E destination (FX-bus 0-63), default 4
+* 13 - left, F destination (FX-bus 0-63), default 5
+* 14 - left, G destination (FX-bus 0-63), default 6
+* 15 - left, H destination (FX-bus 0-63), default 7
* 16 - right, A destination (FX-bus 0-63), default 0
* 17 - right, B destination (FX-bus 0-63), default 1
* 18 - right, C destination (FX-bus 0-63), default 2
* 19 - right, D destination (FX-bus 0-63), default 3
-* 20 - right, E destination (FX-bus 0-63), default 0
-* 21 - right, F destination (FX-bus 0-63), default 0
-* 22 - right, G destination (FX-bus 0-63), default 0
-* 23 - right, H destination (FX-bus 0-63), default 0
+* 20 - right, E destination (FX-bus 0-63), default 4
+* 21 - right, F destination (FX-bus 0-63), default 5
+* 22 - right, G destination (FX-bus 0-63), default 6
+* 23 - right, H destination (FX-bus 0-63), default 7
Don't forget that it's illegal to assign a channel to the same FX-bus accumulator
more than once (it means 0=0 && 1=0 is an invalid combination).
diff --git a/Documentation/sound/cards/index.rst b/Documentation/sound/cards/index.rst
index c016f8c3b88b..49c1f2f688f8 100644
--- a/Documentation/sound/cards/index.rst
+++ b/Documentation/sound/cards/index.rst
@@ -17,3 +17,4 @@ Card-Specific Information
hdspm
serial-u16550
img-spdif-in
+ pcmtest
diff --git a/Documentation/sound/cards/pcmtest.rst b/Documentation/sound/cards/pcmtest.rst
new file mode 100644
index 000000000000..e163522f3205
--- /dev/null
+++ b/Documentation/sound/cards/pcmtest.rst
@@ -0,0 +1,120 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+The Virtual PCM Test Driver
+===========================
+
+The Virtual PCM Test Driver emulates a generic PCM device, and can be used for
+testing/fuzzing of the userspace ALSA applications, as well as for testing/fuzzing of
+the PCM middle layer. Additionally, it can be used for simulating hard to reproduce
+problems with PCM devices.
+
+What can this driver do?
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+At this moment the driver can do the following things:
+ * Simulate both capture and playback processes
+ * Generate random or pattern-based capturing data
+ * Inject delays into the playback and capturing processes
+ * Inject errors during the PCM callbacks
+
+It supports up to 8 substreams and 4 channels. Also it supports both interleaved and
+non-interleaved access modes.
+
+Also, this driver can check the playback stream for containing the predefined pattern,
+which is used in the corresponding selftest (alsa/pcmtest-test.sh) to check the PCM middle
+layer data transferring functionality. Additionally, this driver redefines the default
+RESET ioctl, and the selftest covers this PCM API functionality as well.
+
+Configuration
+-------------
+
+The driver has several parameters besides the common ALSA module parameters:
+
+ * fill_mode (bool) - Buffer fill mode (see below)
+ * inject_delay (int)
+ * inject_hwpars_err (bool)
+ * inject_prepare_err (bool)
+ * inject_trigger_err (bool)
+
+
+Capture Data Generation
+-----------------------
+
+The driver has two modes of data generation: the first (0 in the fill_mode parameter)
+means random data generation, the second (1 in the fill_mode) - pattern-based
+data generation. Let's look at the second mode.
+
+First of all, you may want to specify the pattern for data generation. You can do it
+by writing the pattern to the debugfs file. There are pattern buffer debugfs entries
+for each channel, as well as entries which contain the pattern buffer length.
+
+ * /sys/kernel/debug/pcmtest/fill_pattern[0-3]
+ * /sys/kernel/debug/pcmtest/fill_pattern[0-3]_len
+
+To set the pattern for the channel 0 you can execute the following command:
+
+.. code-block:: bash
+
+ echo -n mycoolpattern > /sys/kernel/debug/pcmtest/fill_pattern0
+
+Then, after every capture action performed on the 'pcmtest' device the buffer for the
+channel 0 will contain 'mycoolpatternmycoolpatternmycoolpatternmy...'.
+
+The pattern itself can be up to 4096 bytes long.
+
+Delay injection
+---------------
+
+The driver has 'inject_delay' parameter, which has very self-descriptive name and
+can be used for time delay/speedup simulations. The parameter has integer type, and
+it means the delay added between module's internal timer ticks.
+
+If the 'inject_delay' value is positive, the buffer will be filled slower, if it is
+negative - faster. You can try it yourself by starting a recording in any
+audiorecording application (like Audacity) and selecting the 'pcmtest' device as a
+source.
+
+This parameter can be also used for generating a huge amount of sound data in a very
+short period of time (with the negative 'inject_delay' value).
+
+Errors injection
+----------------
+
+This module can be used for injecting errors into the PCM communication process. This
+action can help you to figure out how the userspace ALSA program behaves under unusual
+circumstances.
+
+For example, you can make all 'hw_params' PCM callback calls return EBUSY error by
+writing '1' to the 'inject_hwpars_err' module parameter:
+
+.. code-block:: bash
+
+ echo 1 > /sys/module/snd_pcmtest/parameters/inject_hwpars_err
+
+Errors can be injected into the following PCM callbacks:
+
+ * hw_params (EBUSY)
+ * prepare (EINVAL)
+ * trigger (EINVAL)
+
+Playback test
+-------------
+
+This driver can be also used for the playback functionality testing - every time you
+write the playback data to the 'pcmtest' PCM device and close it, the driver checks the
+buffer for containing the looped pattern (which is specified in the fill_pattern
+debugfs file for each channel). If the playback buffer content represents the looped
+pattern, 'pc_test' debugfs entry is set into '1'. Otherwise, the driver sets it to '0'.
+
+ioctl redefinition test
+-----------------------
+
+The driver redefines the 'reset' ioctl, which is default for all PCM devices. To test
+this functionality, we can trigger the reset ioctl and check the 'ioctl_test' debugfs
+entry:
+
+.. code-block:: bash
+
+ cat /sys/kernel/debug/pcmtest/ioctl_test
+
+If the ioctl is triggered successfully, this file will contain '1', and '0' otherwise.
diff --git a/Documentation/sound/cards/sb-live-mixer.rst b/Documentation/sound/cards/sb-live-mixer.rst
index 819886634400..4dd9bfe01bd8 100644
--- a/Documentation/sound/cards/sb-live-mixer.rst
+++ b/Documentation/sound/cards/sb-live-mixer.rst
@@ -258,7 +258,7 @@ PCM stream related controls
``name='EMU10K1 PCM Volume',index 0-31``
----------------------------------------
-Channel volume attenuation in range 0-0xffff. The maximum value (no
+Channel volume attenuation in range 0-0x1fffd. The middle value (no
attenuation) is default. The channel mapping for three values is
as follows:
diff --git a/Documentation/sound/designs/compress-offload.rst b/Documentation/sound/designs/compress-offload.rst
index 935f325dbc77..655624f77092 100644
--- a/Documentation/sound/designs/compress-offload.rst
+++ b/Documentation/sound/designs/compress-offload.rst
@@ -268,11 +268,12 @@ with setting of meta_data and signalling for next track ::
| |
| V
| +----------+
- | | |
- | |NEXT_TRACK|
- | | |
- | +----------+
- | |
+ | compr_set_params() | |
+ | +-----------|NEXT_TRACK|
+ | | | |
+ | | +--+-------+
+ | | | |
+ | +--------------+ |
| |
| | compr_partial_drain()
| |
diff --git a/Documentation/sound/designs/index.rst b/Documentation/sound/designs/index.rst
index 1eb08e7bae52..b79db9ad8732 100644
--- a/Documentation/sound/designs/index.rst
+++ b/Documentation/sound/designs/index.rst
@@ -15,3 +15,4 @@ Designs and Implementations
oss-emulation
seq-oss
jack-injection
+ midi-2.0
diff --git a/Documentation/sound/designs/midi-2.0.rst b/Documentation/sound/designs/midi-2.0.rst
new file mode 100644
index 000000000000..27d0d3dea1b0
--- /dev/null
+++ b/Documentation/sound/designs/midi-2.0.rst
@@ -0,0 +1,378 @@
+=================
+MIDI 2.0 on Linux
+=================
+
+General
+=======
+
+MIDI 2.0 is an extended protocol for providing higher resolutions and
+more fine controls over the legacy MIDI 1.0. The fundamental changes
+introduced for supporting MIDI 2.0 are:
+
+- Support of Universal MIDI Packet (UMP)
+- Support of MIDI 2.0 protocol messages
+- Transparent conversions between UMP and legacy MIDI 1.0 byte stream
+- MIDI-CI for property and profile configurations
+
+UMP is a new container format to hold all MIDI protocol 1.0 and MIDI
+2.0 protocol messages. Unlike the former byte stream, it's 32bit
+aligned, and each message can be put in a single packet. UMP can send
+the events up to 16 "UMP Groups", where each UMP Group contain up to
+16 MIDI channels.
+
+MIDI 2.0 protocol is an extended protocol to achieve the higher
+resolution and more controls over the old MIDI 1.0 protocol.
+
+MIDI-CI is a high-level protocol that can talk with the MIDI device
+for the flexible profiles and configurations. It's represented in the
+form of special SysEx.
+
+For Linux implementations, the kernel supports the UMP transport and
+the encoding/decoding of MIDI protocols on UMP, while MIDI-CI is
+supported in user-space over the standard SysEx.
+
+As of this writing, only USB MIDI device supports the UMP and Linux
+2.0 natively. The UMP support itself is pretty generic, hence it
+could be used by other transport layers, although it could be
+implemented differently (e.g. as a ALSA sequencer client), too.
+
+The access to UMP devices are provided in two ways: the access via
+rawmidi device and the access via ALSA sequencer API.
+
+ALSA sequencer API was extended to allow the payload of UMP packets.
+It's allowed to connect freely between MIDI 1.0 and MIDI 2.0 sequencer
+clients, and the events are converted transparently.
+
+
+Kernel Configuration
+====================
+
+The following new configs are added for supporting MIDI 2.0:
+`CONFIG_SND_UMP`, `CONFIG_SND_UMP_LEGACY_RAWMIDI`,
+`CONFIG_SND_SEQ_UMP`, `CONFIG_SND_SEQ_UMP_CLIENT`, and
+`CONFIG_SND_USB_AUDIO_MIDI_V2`. The first visible one is
+`CONFIG_SND_USB_AUDIO_MIDI_V2`, and when you choose it (to set `=y`),
+the core support for UMP (`CONFIG_SND_UMP`) and the sequencer binding
+(`CONFIG_SND_SEQ_UMP_CLIENT`) will be automatically selected.
+
+Additionally, `CONFIG_SND_UMP_LEGACY_RAWMIDI=y` will enable the
+support for the legacy raw MIDI device for UMP Endpoints.
+
+
+Rawmidi Device with USB MIDI 2.0
+================================
+
+When a device supports MIDI 2.0, the USB-audio driver probes and uses
+the MIDI 2.0 interface (that is found always at the altset 1) as
+default instead of the MIDI 1.0 interface (at altset 0). You can
+switch back to the binding with the old MIDI 1.0 interface by passing
+`midi2_enable=0` option to snd-usb-audio driver module, too.
+
+The USB audio driver tries to query the UMP Endpoint and UMP Function
+Block information that are provided since UMP v1.1, and builds up the
+topology based on those information. When the device is older and
+doesn't respond to the new UMP inquiries, the driver falls back and
+builds the topology based on Group Terminal Block (GTB) information
+from the USB descriptor. Some device might be screwed up by the
+unexpected UMP command; in such a case, pass `midi2_probe=0` option to
+snd-usb-audio driver for skipping the UMP v1.1 inquiries.
+
+When the MIDI 2.0 device is probed, the kernel creates a rawmidi
+device for each UMP Endpoint of the device. Its device name is
+`/dev/snd/umpC*D*` and different from the standard rawmidi device name
+`/dev/snd/midiC*D*` for MIDI 1.0, in order to avoid confusing the
+legacy applications accessing mistakenly to UMP devices.
+
+You can read and write UMP packet data directly from/to this UMP
+rawmidi device. For example, reading via `hexdump` like below will
+show the incoming UMP packets of the card 0 device 0 in the hex
+format::
+
+ % hexdump -C /dev/snd/umpC0D0
+ 00000000 01 07 b0 20 00 07 b0 20 64 3c 90 20 64 3c 80 20 |... ... d<. d<. |
+
+Unlike the MIDI 1.0 byte stream, UMP is a 32bit packet, and the size
+for reading or writing the device is also aligned to 32bit (which is 4
+bytes).
+
+The 32-bit words in the UMP packet payload are always in CPU native
+endianness. Transport drivers are responsible to convert UMP words
+from / to system endianness to required transport endianness / byte
+order.
+
+When `CONFIG_SND_UMP_LEGACY_RAWMIDI` is set, the driver creates
+another standard raw MIDI device additionally as `/dev/snd/midiC*D*`.
+This contains 16 substreams, and each substream corresponds to a
+(0-based) UMP Group. Legacy applications can access to the specified
+group via each substream in MIDI 1.0 byte stream format. With the
+ALSA rawmidi API, you can open the arbitrary substream, while just
+opening `/dev/snd/midiC*D*` will end up with opening the first
+substream.
+
+Each UMP Endpoint can provide the additional information, constructed
+from the information inquired via UMP 1.1 Stream messages or USB MIDI
+2.0 descriptors. And a UMP Endpoint may contain one or more UMP
+Blocks, where UMP Block is an abstraction introduced in the ALSA UMP
+implementations to represent the associations among UMP Groups. UMP
+Block corresponds to Function Block in UMP 1.1 specification. When
+UMP 1.1 Function Block information isn't available, it's filled
+partially from Group Terminal Block (GTB) as defined in USB MIDI 2.0
+specifications.
+
+The information of UMP Endpoints and UMP Blocks are found in the proc
+file `/proc/asound/card*/midi*`. For example::
+
+ % cat /proc/asound/card1/midi0
+ ProtoZOA MIDI
+
+ Type: UMP
+ EP Name: ProtoZOA
+ EP Product ID: ABCD12345678
+ UMP Version: 0x0000
+ Protocol Caps: 0x00000100
+ Protocol: 0x00000100
+ Num Blocks: 3
+
+ Block 0 (ProtoZOA Main)
+ Direction: bidirection
+ Active: Yes
+ Groups: 1-1
+ Is MIDI1: No
+
+ Block 1 (ProtoZOA Ext IN)
+ Direction: output
+ Active: Yes
+ Groups: 2-2
+ Is MIDI1: Yes (Low Speed)
+ ....
+
+Note that `Groups` field shown in the proc file above indicates the
+1-based UMP Group numbers (from-to).
+
+Those additional UMP Endpoint and UMP Block information can be
+obtained via the new ioctls `SNDRV_UMP_IOCTL_ENDPOINT_INFO` and
+`SNDRV_UMP_IOCTL_BLOCK_INFO`, respectively.
+
+The rawmidi name and the UMP Endpoint name are usually identical, and
+in the case of USB MIDI, it's taken from `iInterface` of the
+corresponding USB MIDI interface descriptor. If it's not provided,
+it's copied from `iProduct` of the USB device descriptor as a
+fallback.
+
+The Endpoint Product ID is a string field and supposed to be unique.
+It's copied from `iSerialNumber` of the device for USB MIDI.
+
+The protocol capabilities and the actual protocol bits are defined in
+`asound.h`.
+
+
+ALSA Sequencer with USB MIDI 2.0
+================================
+
+In addition to the rawmidi interfaces, ALSA sequencer interface
+supports the new UMP MIDI 2.0 device, too. Now, each ALSA sequencer
+client may set its MIDI version (0, 1 or 2) to declare itself being
+either the legacy, UMP MIDI 1.0 or UMP MIDI 2.0 device, respectively.
+The first, legacy client is the one that sends/receives the old
+sequencer event as was. Meanwhile, UMP MIDI 1.0 and 2.0 clients send
+and receive in the extended event record for UMP. The MIDI version is
+seen in the new `midi_version` field of `snd_seq_client_info`.
+
+A UMP packet can be sent/received in a sequencer event embedded by
+specifying the new event flag bit `SNDRV_SEQ_EVENT_UMP`. When this
+flag is set, the event has 16 byte (128 bit) data payload for holding
+the UMP packet. Without the `SNDRV_SEQ_EVENT_UMP` bit flag, the event
+is treated as a legacy event as it was (with max 12 byte data
+payload).
+
+With `SNDRV_SEQ_EVENT_UMP` flag set, the type field of a UMP sequencer
+event is ignored (but it should be set to 0 as default).
+
+The type of each client can be seen in `/proc/asound/seq/clients`.
+For example::
+
+ % cat /proc/asound/seq/clients
+ Client info
+ cur clients : 3
+ ....
+ Client 14 : "Midi Through" [Kernel Legacy]
+ Port 0 : "Midi Through Port-0" (RWe-)
+ Client 20 : "ProtoZOA" [Kernel UMP MIDI1]
+ UMP Endpoint: ProtoZOA
+ UMP Block 0: ProtoZOA Main [Active]
+ Groups: 1-1
+ UMP Block 1: ProtoZOA Ext IN [Active]
+ Groups: 2-2
+ UMP Block 2: ProtoZOA Ext OUT [Active]
+ Groups: 3-3
+ Port 0 : "MIDI 2.0" (RWeX) [In/Out]
+ Port 1 : "ProtoZOA Main" (RWeX) [In/Out]
+ Port 2 : "ProtoZOA Ext IN" (-We-) [Out]
+ Port 3 : "ProtoZOA Ext OUT" (R-e-) [In]
+
+Here you can find two types of kernel clients, "Legacy" for client 14,
+and "UMP MIDI1" for client 20, which is a USB MIDI 2.0 device.
+A USB MIDI 2.0 client gives always the port 0 as "MIDI 2.0" and the
+rest ports from 1 for each UMP Group (e.g. port 1 for Group 1).
+In this example, the device has three active groups (Main, Ext IN and
+Ext OUT), and those are exposed as sequencer ports from 1 to 3.
+The "MIDI 2.0" port is for a UMP Endpoint, and its difference from
+other UMP Group ports is that UMP Endpoint port sends the events from
+the all ports on the device ("catch-all"), while each UMP Group port
+sends only the events from the given UMP Group.
+Also, UMP groupless messages (such as the UMP message type 0x0f) are
+sent only to the UMP Endpoint port.
+
+Note that, although each UMP sequencer client usually creates 16
+ports, those ports that don't belong to any UMP Blocks (or belonging
+to inactive UMP Blocks) are marked as inactive, and they don't appear
+in the proc outputs. In the example above, the sequencer ports from 4
+to 16 are present but not shown there.
+
+The proc file above shows the UMP Block information, too. The same
+entry (but with more detailed information) is found in the rawmidi
+proc output.
+
+When clients are connected between different MIDI versions, the events
+are translated automatically depending on the client's version, not
+only between the legacy and the UMP MIDI 1.0/2.0 types, but also
+between UMP MIDI 1.0 and 2.0 types, too. For example, running
+`aseqdump` program on the ProtoZOA Main port in the legacy mode will
+give you the output like::
+
+ % aseqdump -p 20:1
+ Waiting for data. Press Ctrl+C to end.
+ Source Event Ch Data
+ 20:1 Note on 0, note 60, velocity 100
+ 20:1 Note off 0, note 60, velocity 100
+ 20:1 Control change 0, controller 11, value 4
+
+When you run `aseqdump` in MIDI 2.0 mode, it'll receive the high
+precision data like::
+
+ % aseqdump -u 2 -p 20:1
+ Waiting for data. Press Ctrl+C to end.
+ Source Event Ch Data
+ 20:1 Note on 0, note 60, velocity 0xc924, attr type = 0, data = 0x0
+ 20:1 Note off 0, note 60, velocity 0xc924, attr type = 0, data = 0x0
+ 20:1 Control change 0, controller 11, value 0x2000000
+
+while the data is automatically converted by ALSA sequencer core.
+
+
+Rawmidi API Extensions
+======================
+
+* The additional UMP Endpoint information can be obtained via the new
+ ioctl `SNDRV_UMP_IOCTL_ENDPOINT_INFO`. It contains the associated
+ card and device numbers, the bit flags, the protocols, the number of
+ UMP Blocks, the name string of the endpoint, etc.
+
+ The protocols are specified in two field, the protocol capabilities
+ and the current protocol. Both contain the bit flags specifying the
+ MIDI protocol version (`SNDRV_UMP_EP_INFO_PROTO_MIDI1` or
+ `SNDRV_UMP_EP_INFO_PROTO_MIDI2`) in the upper byte and the jitter
+ reduction timestamp (`SNDRV_UMP_EP_INFO_PROTO_JRTS_TX` and
+ `SNDRV_UMP_EP_INFO_PROTO_JRTS_RX`) in the lower byte.
+
+ A UMP Endpoint may contain up to 32 UMP Blocks, and the number of
+ the currently assigned blocks are shown in the Endpoint information.
+
+* Each UMP Block information can be obtained via another new ioctl
+ `SNDRV_UMP_IOCTL_BLOCK_INFO`. The block ID number (0-based) has to
+ be passed for the block to query. The received data contains the
+ associated the direction of the block, the first associated group ID
+ (0-based) and the number of groups, the name string of the block,
+ etc.
+
+ The direction is either `SNDRV_UMP_DIR_INPUT`,
+ `SNDRV_UMP_DIR_OUTPUT` or `SNDRV_UMP_DIR_BIDIRECTION`.
+
+* For the device supports UMP v1.1, the UMP MIDI protocol can be
+ switched via "Stream Configuration Request" message (UMP type 0x0f,
+ status 0x05). When UMP core receives such a message, it updates the
+ UMP EP info and the corresponding sequencer clients as well.
+
+
+Control API Extensions
+======================
+
+* The new ioctl `SNDRV_CTL_IOCTL_UMP_NEXT_DEVICE` is introduced for
+ querying the next UMP rawmidi device, while the existing ioctl
+ `SNDRV_CTL_IOCTL_RAWMIDI_NEXT_DEVICE` queries only the legacy
+ rawmidi devices.
+
+ For setting the subdevice (substream number) to be opened, use the
+ ioctl `SNDRV_CTL_IOCTL_RAWMIDI_PREFER_SUBDEVICE` like the normal
+ rawmidi.
+
+* Two new ioctls `SNDRV_CTL_IOCTL_UMP_ENDPOINT_INFO` and
+ `SNDRV_CTL_IOCTL_UMP_BLOCK_INFO` provide the UMP Endpoint and UMP
+ Block information of the specified UMP device via ALSA control API
+ without opening the actual (UMP) rawmidi device.
+ The `card` field is ignored upon inquiry, always tied with the card
+ of the control interface.
+
+
+Sequencer API Extensions
+========================
+
+* `midi_version` field is added to `snd_seq_client_info` to indicate
+ the current MIDI version (either 0, 1 or 2) of each client.
+ When `midi_version` is 1 or 2, the alignment of read from a UMP
+ sequencer client is also changed from the former 28 bytes to 32
+ bytes for the extended payload. The alignment size for the write
+ isn't changed, but each event size may differ depending on the new
+ bit flag below.
+
+* `SNDRV_SEQ_EVENT_UMP` flag bit is added for each sequencer event
+ flags. When this bit flag is set, the sequencer event is extended
+ to have a larger payload of 16 bytes instead of the legacy 12
+ bytes, and the event contains the UMP packet in the payload.
+
+* The new sequencer port type bit (`SNDRV_SEQ_PORT_TYPE_MIDI_UMP`)
+ indicates the port being UMP-capable.
+
+* The sequencer ports have new capability bits to indicate the
+ inactive ports (`SNDRV_SEQ_PORT_CAP_INACTIVE`) and the UMP Endpoint
+ port (`SNDRV_SEQ_PORT_CAP_UMP_ENDPOINT`).
+
+* The event conversion of ALSA sequencer clients can be suppressed the
+ new filter bit `SNDRV_SEQ_FILTER_NO_CONVERT` set to the client info.
+ For example, the kernel pass-through client (`snd-seq-dummy`) sets
+ this flag internally.
+
+* The port information gained the new field `direction` to indicate
+ the direction of the port (either `SNDRV_SEQ_PORT_DIR_INPUT`,
+ `SNDRV_SEQ_PORT_DIR_OUTPUT` or `SNDRV_SEQ_PORT_DIR_BIDIRECTION`).
+
+* Another additional field for the port information is `ump_group`
+ which specifies the associated UMP Group Number (1-based).
+ When it's non-zero, the UMP group field in the UMP packet updated
+ upon delivery to the specified group (corrected to be 0-based).
+ Each sequencer port is supposed to set this field if it's a port to
+ specific to a certain UMP group.
+
+* Each client may set the additional event filter for UMP Groups in
+ `group_filter` bitmap. The filter consists of bitmap from 1-based
+ Group numbers. For example, when the bit 1 is set, messages from
+ Group 1 (i.e. the very first group) are filtered and not delivered.
+ The bit 0 is used for filtering UMP groupless messages.
+
+* Two new ioctls are added for UMP-capable clients:
+ `SNDRV_SEQ_IOCTL_GET_CLIENT_UMP_INFO` and
+ `SNDRV_SEQ_IOCTL_SET_CLIENT_UMP_INFO`. They are used to get and set
+ either `snd_ump_endpoint_info` or `snd_ump_block_info` data
+ associated with the sequencer client. The USB MIDI driver provides
+ those information from the underlying UMP rawmidi, while a
+ user-space client may provide its own data via `*_SET` ioctl.
+ For an Endpoint data, pass 0 to the `type` field, while for a Block
+ data, pass the block number + 1 to the `type` field.
+ Setting the data for a kernel client shall result in an error.
+
+* With UMP 1.1, Function Block information may be changed
+ dynamically. When the update of Function Block is received from the
+ device, ALSA sequencer core changes the corresponding sequencer port
+ name and attributes accordingly, and notifies the changes via the
+ announcement to the ALSA sequencer system port, similarly like the
+ normal port change notification.