mirror of https://lore.kernel.org/lkml/
 help / color / mirror / Atom feed
From: Takashi Iwai <tiwai@suse.de>
To: alsa-devel@alsa-project.org
Cc: linux-kernel@vger.kernel.org
Subject: [PATCH 10/10] ALSA: docs: Update MIDI 2.0 documentation for UMP 1.1 enhancement
Date: Mon, 12 Jun 2023 10:10:54 +0200	[thread overview]
Message-ID: <20230612081054.17200-11-tiwai@suse.de> (raw)
In-Reply-To: <20230612081054.17200-1-tiwai@suse.de>

There have been a few enhancements for the new UMP 1.1 features.
Update the documentation accordingly.

Signed-off-by: Takashi Iwai <tiwai@suse.de>
---
 Documentation/sound/designs/midi-2.0.rst | 39 ++++++++++++++++++++----
 1 file changed, 33 insertions(+), 6 deletions(-)

diff --git a/Documentation/sound/designs/midi-2.0.rst b/Documentation/sound/designs/midi-2.0.rst
index d55b0a4c6acb..27d0d3dea1b0 100644
--- a/Documentation/sound/designs/midi-2.0.rst
+++ b/Documentation/sound/designs/midi-2.0.rst
@@ -68,6 +68,15 @@ 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
@@ -101,11 +110,15 @@ opening `/dev/snd/midiC*D*` will end up with opening the first
 substream.
 
 Each UMP Endpoint can provide the additional information, constructed
-from 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 Group Terminal Block (GTB) in USB
-MIDI 2.0 specifications but provide a few more generic information.
+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::
 
@@ -207,6 +220,8 @@ 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
@@ -273,6 +288,11 @@ Rawmidi API Extensions
   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
 ======================
@@ -337,7 +357,7 @@ Sequencer API Extensions
   `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 reserved for future use.
+  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
@@ -349,3 +369,10 @@ Sequencer API Extensions
   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.
-- 
2.35.3


      parent reply	other threads:[~2023-06-12  8:12 UTC|newest]

Thread overview: 11+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2023-06-12  8:10 [PATCH 00/10] ALSA: Catch up MIDI 2.0 updates for UMP 1.1 Takashi Iwai
2023-06-12  8:10 ` [PATCH 01/10] ALSA: ump: Add more attributes to UMP EP and FB info Takashi Iwai
2023-06-12  8:10 ` [PATCH 02/10] ALSA: ump: Support UMP Endpoint and Function Block parsing Takashi Iwai
2023-06-12  8:10 ` [PATCH 03/10] ALSA: usb-audio: Parse UMP Endpoint and Function Blocks at first Takashi Iwai
2023-06-12  8:10 ` [PATCH 04/10] ALSA: usb-audio: Add midi2_ump_probe option Takashi Iwai
2023-06-12  8:10 ` [PATCH 05/10] ALSA: seq: ump: Handle groupless messages Takashi Iwai
2023-06-12  8:10 ` [PATCH 06/10] ALSA: seq: ump: Handle FB info update Takashi Iwai
2023-06-12  8:10 ` [PATCH 07/10] ALSA: seq: ump: Notify port changes to system port Takashi Iwai
2023-06-12  8:10 ` [PATCH 08/10] ALSA: seq: ump: Notify UMP protocol change to sequencer Takashi Iwai
2023-06-12  8:10 ` [PATCH 09/10] ALSA: ump: Add info flag bit for static blocks Takashi Iwai
2023-06-12  8:10 ` Takashi Iwai [this message]

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20230612081054.17200-11-tiwai@suse.de \
    --to=tiwai@suse.de \
    --cc=alsa-devel@alsa-project.org \
    --cc=linux-kernel@vger.kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox

all inboxes | Powered by JetHome®