Merge branch 'topic/midi20' into for-next

As the updated MIDI 2.0 spec has been published freshly, this is a
catch up to add the support for new specs, especially UMP v1.1
features, on Linux kernel.

The new UMP v1.1 introduced the concept of Function Blocks (FB), which
is a kind of superset of USB MIDI 2.0 Group Terminal Blocks (GTB).
The patch set adds the support for FB as the primary information
source while keeping the parse of GTB as fallback.  Also UMP v1.1
supports the groupless messages, the protocol switch, static FBs, and
other new fundamental features, and those are supported as well.

Link: https://www.midi.org/midi-articles/details-about-midi-2-0-midi-ci-profiles-and-property-exchange
Link: https://lore.kernel.org/r/20230612081054.17200-1-tiwai@suse.de
Signed-off-by: Takashi Iwai <tiwai@suse.de>

Author: tiwai

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.

include/sound/ump.h

@@ -24,6 +24,13 @@ struct snd_ump_endpoint {
 	void *private_data;
 	void (*private_free)(struct snd_ump_endpoint *ump);
 
+	/* UMP Stream message processing */
+	u32 stream_wait_for;	/* expected stream message status */
+	bool stream_finished;	/* set when message has been processed */
+	bool parsed;		/* UMP / FB parse finished? */
+	wait_queue_head_t stream_wait;
+	struct snd_rawmidi_file stream_rfile;
+
 	struct list_head block_list;	/* list of snd_ump_block objects */
 
 	/* intermediate buffer for UMP input */
@@ -63,6 +70,9 @@ struct snd_ump_ops {
 struct snd_seq_ump_ops {
 	void (*input_receive)(struct snd_ump_endpoint *ump,
 			      const u32 *data, int words);
+	int (*notify_fb_change)(struct snd_ump_endpoint *ump,
+				struct snd_ump_block *fb);
+	int (*switch_protocol)(struct snd_ump_endpoint *ump);
 };
 
 struct snd_ump_block {
@@ -80,6 +90,7 @@ struct snd_ump_block {
 int snd_ump_endpoint_new(struct snd_card *card, char *id, int device,
 			 int output, int input,
 			 struct snd_ump_endpoint **ump_ret);
+int snd_ump_parse_endpoint(struct snd_ump_endpoint *ump);
 int snd_ump_block_new(struct snd_ump_endpoint *ump, unsigned int blk,
 		      unsigned int direction, unsigned int first_group,
 		      unsigned int num_groups, struct snd_ump_block **blk_ret);
@@ -109,6 +120,8 @@ enum {
 	UMP_MSG_TYPE_DATA			= 0x03,
 	UMP_MSG_TYPE_MIDI2_CHANNEL_VOICE	= 0x04,
 	UMP_MSG_TYPE_EXTENDED_DATA		= 0x05,
+	UMP_MSG_TYPE_FLEX_DATA			= 0x0d,
+	UMP_MSG_TYPE_STREAM			= 0x0f,
 };
 
 /* MIDI 2.0 SysEx / Data Status; same values for both 7-bit and 8-bit SysEx */
@@ -119,6 +132,62 @@ enum {
 	UMP_SYSEX_STATUS_END			= 3,
 };
 
+/* UMP Utility Type Status (type 0x0) */
+enum {
+	UMP_UTILITY_MSG_STATUS_NOOP		= 0x00,
+	UMP_UTILITY_MSG_STATUS_JR_CLOCK		= 0x01,
+	UMP_UTILITY_MSG_STATUS_JR_TSTAMP	= 0x02,
+	UMP_UTILITY_MSG_STATUS_DCTPQ		= 0x03,
+	UMP_UTILITY_MSG_STATUS_DC		= 0x04,
+};
+
+/* UMP Stream Message Status (type 0xf) */
+enum {
+	UMP_STREAM_MSG_STATUS_EP_DISCOVERY	= 0x00,
+	UMP_STREAM_MSG_STATUS_EP_INFO		= 0x01,
+	UMP_STREAM_MSG_STATUS_DEVICE_INFO	= 0x02,
+	UMP_STREAM_MSG_STATUS_EP_NAME		= 0x03,
+	UMP_STREAM_MSG_STATUS_PRODUCT_ID	= 0x04,
+	UMP_STREAM_MSG_STATUS_STREAM_CFG_REQUEST = 0x05,
+	UMP_STREAM_MSG_STATUS_STREAM_CFG	= 0x06,
+	UMP_STREAM_MSG_STATUS_FB_DISCOVERY	= 0x10,
+	UMP_STREAM_MSG_STATUS_FB_INFO		= 0x11,
+	UMP_STREAM_MSG_STATUS_FB_NAME		= 0x12,
+	UMP_STREAM_MSG_STATUS_START_CLIP	= 0x20,
+	UMP_STREAM_MSG_STATUS_END_CLIP		= 0x21,
+};
+
+/* UMP Endpoint Discovery filter bitmap */
+enum {
+	UMP_STREAM_MSG_REQUEST_EP_INFO		= (1U << 0),
+	UMP_STREAM_MSG_REQUEST_DEVICE_INFO	= (1U << 1),
+	UMP_STREAM_MSG_REQUEST_EP_NAME		= (1U << 2),
+	UMP_STREAM_MSG_REQUEST_PRODUCT_ID	= (1U << 3),
+	UMP_STREAM_MSG_REQUEST_STREAM_CFG	= (1U << 4),
+};
+
+/* UMP Function Block Discovery filter bitmap */
+enum {
+	UMP_STREAM_MSG_REQUEST_FB_INFO		= (1U << 0),
+	UMP_STREAM_MSG_REQUEST_FB_NAME		= (1U << 1),
+};
+
+/* UMP Endpoint Info capability bits (used for protocol request/notify, too) */
+enum {
+	UMP_STREAM_MSG_EP_INFO_CAP_TXJR		= (1U << 0), /* Sending JRTS */
+	UMP_STREAM_MSG_EP_INFO_CAP_RXJR		= (1U << 1), /* Receiving JRTS */
+	UMP_STREAM_MSG_EP_INFO_CAP_MIDI1	= (1U << 8), /* MIDI 1.0 */
+	UMP_STREAM_MSG_EP_INFO_CAP_MIDI2	= (1U << 9), /* MIDI 2.0 */
+};
+
+/* UMP EP / FB name string format; same as SysEx string handling */
+enum {
+	UMP_STREAM_MSG_FORMAT_SINGLE		= 0,
+	UMP_STREAM_MSG_FORMAT_START		= 1,
+	UMP_STREAM_MSG_FORMAT_CONTINUE		= 2,
+	UMP_STREAM_MSG_FORMAT_END		= 3,
+};
+
 /*
  * Helpers for retrieving / filling bits from UMP
  */
@@ -172,4 +241,24 @@ static inline unsigned char ump_sysex_message_length(u32 data)
 	return (data >> 16) & 0xf;
 }
 
+/* For Stream Messages */
+static inline unsigned char ump_stream_message_format(u32 data)
+{
+	return (data >> 26) & 0x03;
+}
+
+static inline unsigned int ump_stream_message_status(u32 data)
+{
+	return (data >> 16) & 0x3ff;
+}
+
+static inline u32 ump_stream_compose(unsigned char status, unsigned short form)
+{
+	return (UMP_MSG_TYPE_STREAM << 28) | ((u32)form << 26) |
+		((u32)status << 16);
+}
+
+#define ump_is_groupless_msg(type) \
+	((type) == UMP_MSG_TYPE_UTILITY || (type) == UMP_MSG_TYPE_STREAM)
+
 #endif /* __SOUND_UMP_H */