Commit 508b662b authored by Takashi Iwai's avatar Takashi Iwai
Browse files

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: default avatarTakashi Iwai <tiwai@suse.de>
parents 9b446941 febdfa0e

Documentation/sound/designs/midi-2.0.rst

+33 −6
Original line number Diff line number Diff line
@@ -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

+89 −0
Original line number Diff line number Diff line
@@ -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 */

include/sound/ump_msg.h

+225 −0
Original line number Diff line number Diff line
@@ -537,4 +537,229 @@ union snd_ump_midi2_msg { 
	u32 raw[2];

};



/* UMP Stream Message: Endpoint Discovery (128bit) */

struct snd_ump_stream_msg_ep_discovery {

#ifdef __BIG_ENDIAN_BITFIELD

	/* 0 */

	u32 type:4;

	u32 format:2;

	u32 status:10;

	u32 ump_version_major:8;

	u32 ump_version_minor:8;

	/* 1 */

	u32 reserved:24;

	u32 filter_bitmap:8;

	/* 2-3 */

	u32 reserved2[2];

#else

	/* 0 */

	u32 ump_version_minor:8;

	u32 ump_version_major:8;

	u32 status:10;

	u32 format:2;

	u32 type:4;

	/* 1 */

	u32 filter_bitmap:8;

	u32 reserved:24;

	/* 2-3 */

	u32 reserved2[2];

#endif

} __packed;



/* UMP Stream Message: Endpoint Info Notification (128bit) */

struct snd_ump_stream_msg_ep_info {

#ifdef __BIG_ENDIAN_BITFIELD

	/* 0 */

	u32 type:4;

	u32 format:2;

	u32 status:10;

	u32 ump_version_major:8;

	u32 ump_version_minor:8;

	/* 1 */

	u32 static_function_block:1;

	u32 num_function_blocks:7;

	u32 reserved:8;

	u32 protocol:8;

	u32 reserved2:6;

	u32 jrts:2;

	/* 2-3 */

	u32 reserved3[2];

#else

	/* 0 */

	u32 ump_version_minor:8;

	u32 ump_version_major:8;

	u32 status:10;

	u32 format:2;

	u32 type:4;

	/* 1 */

	u32 jrts:2;

	u32 reserved2:6;

	u32 protocol:8;

	u32 reserved:8;

	u32 num_function_blocks:7;

	u32 static_function_block:1;

	/* 2-3 */

	u32 reserved3[2];

#endif

} __packed;



/* UMP Stream Message: Device Info Notification (128bit) */

struct snd_ump_stream_msg_devince_info {

#ifdef __BIG_ENDIAN_BITFIELD

	/* 0 */

	u32 type:4;

	u32 format:2;

	u32 status:10;

	u32 reserved:16;

	/* 1 */

	u32 manufacture_id;

	/* 2 */

	u8 family_lsb;

	u8 family_msb;

	u8 model_lsb;

	u8 model_msb;

	/* 3 */

	u32 sw_revision;

#else

	/* 0 */

	u32 reserved:16;

	u32 status:10;

	u32 format:2;

	u32 type:4;

	/* 1 */

	u32 manufacture_id;

	/* 2 */

	u8 model_msb;

	u8 model_lsb;

	u8 family_msb;

	u8 family_lsb;

	/* 3 */

	u32 sw_revision;

#endif

} __packed;



/* UMP Stream Message: Stream Config Request / Notification (128bit) */

struct snd_ump_stream_msg_stream_cfg {

#ifdef __BIG_ENDIAN_BITFIELD

	/* 0 */

	u32 type:4;

	u32 format:2;

	u32 status:10;

	u32 protocol:8;

	u32 reserved:6;

	u32 jrts:2;

	/* 1-3 */

	u32 reserved2[3];

#else

	/* 0 */

	u32 jrts:2;

	u32 reserved:6;

	u32 protocol:8;

	u32 status:10;

	u32 format:2;

	u32 type:4;

	/* 1-3 */

	u32 reserved2[3];

#endif

} __packed;



/* UMP Stream Message: Function Block Discovery (128bit) */

struct snd_ump_stream_msg_fb_discovery {

#ifdef __BIG_ENDIAN_BITFIELD

	/* 0 */

	u32 type:4;

	u32 format:2;

	u32 status:10;

	u32 function_block_id:8;

	u32 filter:8;

	/* 1-3 */

	u32 reserved[3];

#else

	/* 0 */

	u32 filter:8;

	u32 function_block_id:8;

	u32 status:10;

	u32 format:2;

	u32 type:4;

	/* 1-3 */

	u32 reserved[3];

#endif

} __packed;



/* UMP Stream Message: Function Block Info Notification (128bit) */

struct snd_ump_stream_msg_fb_info {

#ifdef __BIG_ENDIAN_BITFIELD

	/* 0 */

	u32 type:4;

	u32 format:2;

	u32 status:10;

	u32 active:1;

	u32 function_block_id:7;

	u32 reserved:2;

	u32 ui_hint:2;

	u32 midi_10:2;

	u32 direction:2;

	/* 1 */

	u32 first_group:8;

	u32 num_groups:8;

	u32 midi_ci_version:8;

	u32 sysex8_streams:8;

	/* 2-3 */

	u32 reserved2[2];

#else

	/* 0 */

	u32 direction:2;

	u32 midi_10:2;

	u32 ui_hint:2;

	u32 reserved:2;

	u32 function_block_id:7;

	u32 active:1;

	u32 status:10;

	u32 format:2;

	u32 type:4;

	/* 1 */

	u32 sysex8_streams:8;

	u32 midi_ci_version:8;

	u32 num_groups:8;

	u32 first_group:8;

	/* 2-3 */

	u32 reserved2[2];

#endif

} __packed;



/* UMP Stream Message: Function Block Name Notification (128bit) */

struct snd_ump_stream_msg_fb_name {

#ifdef __BIG_ENDIAN_BITFIELD

	/* 0 */

	u16 type:4;

	u16 format:2;

	u16 status:10;

	u8 function_block_id;

	u8 name0;

	/* 1-3 */

	u8 name[12];

#else

	/* 0 */

	u8 name0;

	u8 function_block_id;

	u16 status:10;

	u16 format:2;

	u16 type:4;

	/* 1-3 */

	u8 name[12]; // FIXME: byte order

#endif

} __packed;



/* MIDI 2.0 Stream Messages (128bit) */

union snd_ump_stream_msg {

	struct snd_ump_stream_msg_ep_discovery ep_discovery;

	struct snd_ump_stream_msg_ep_info ep_info;

	struct snd_ump_stream_msg_devince_info device_info;

	struct snd_ump_stream_msg_stream_cfg stream_cfg;

	struct snd_ump_stream_msg_fb_discovery fb_discovery;

	struct snd_ump_stream_msg_fb_info fb_info;

	struct snd_ump_stream_msg_fb_name fb_name;

	u32 raw[4];

};



#endif /* __SOUND_UMP_MSG_H */

include/uapi/sound/asequencer.h

+4 −1
Original line number Diff line number Diff line
@@ -362,7 +362,10 @@ struct snd_seq_client_info { 
	int card;			/* RO: card number[kernel] */

	int pid;			/* RO: pid[user] */

	unsigned int midi_version;	/* MIDI version */

	unsigned int group_filter;	/* UMP group filter bitmap (for 1-based Group indices) */

	unsigned int group_filter;	/* UMP group filter bitmap

					 * (bit 0 = groupless messages,

					 *  bit 1-16 = messages for groups 1-16)

					 */

	char reserved[48];		/* for future use */

};

include/uapi/sound/asound.h

+18 −3
Original line number Diff line number Diff line
@@ -712,7 +712,7 @@ enum { 
 *  Raw MIDI section - /dev/snd/midi??

 */



#define SNDRV_RAWMIDI_VERSION		SNDRV_PROTOCOL_VERSION(2, 0, 3)

#define SNDRV_RAWMIDI_VERSION		SNDRV_PROTOCOL_VERSION(2, 0, 4)



enum {

	SNDRV_RAWMIDI_STREAM_OUTPUT = 0,
@@ -784,6 +784,9 @@ struct snd_rawmidi_status { 
};

#endif



/* UMP EP info flags */

#define SNDRV_UMP_EP_INFO_STATIC_BLOCKS		0x01



/* UMP EP Protocol / JRTS capability bits */

#define SNDRV_UMP_EP_INFO_PROTO_MIDI_MASK	0x0300

#define SNDRV_UMP_EP_INFO_PROTO_MIDI1		0x0100 /* MIDI 1.0 */
@@ -801,7 +804,11 @@ struct snd_ump_endpoint_info { 
	unsigned int protocol;		/* current protocol */

	unsigned int num_blocks;	/* # of function blocks */

	unsigned short version;		/* UMP major/minor version */

	unsigned short padding[7];

	unsigned short family_id;	/* MIDI device family ID */

	unsigned short model_id;	/* MIDI family model ID */

	unsigned int manufacturer_id;	/* MIDI manufacturer ID */

	unsigned char sw_revision[4];	/* software revision */

	unsigned short padding;

	unsigned char name[128];	/* endpoint name string */

	unsigned char product_id[128];	/* unique product id string */

	unsigned char reserved[32];
@@ -816,6 +823,12 @@ struct snd_ump_endpoint_info { 
#define SNDRV_UMP_BLOCK_IS_MIDI1	(1U << 0) /* MIDI 1.0 port w/o restrict */

#define SNDRV_UMP_BLOCK_IS_LOWSPEED	(1U << 1) /* 31.25Kbps B/W MIDI1 port */



/* UMP block user-interface hint */

#define SNDRV_UMP_BLOCK_UI_HINT_UNKNOWN		0x00

#define SNDRV_UMP_BLOCK_UI_HINT_RECEIVER	0x01

#define SNDRV_UMP_BLOCK_UI_HINT_SENDER		0x02

#define SNDRV_UMP_BLOCK_UI_HINT_BOTH		0x03



/* UMP groups and blocks */

#define SNDRV_UMP_MAX_GROUPS		16

#define SNDRV_UMP_MAX_BLOCKS		32
@@ -829,7 +842,9 @@ struct snd_ump_block_info { 
	unsigned char active;		/* Activeness */

	unsigned char first_group;	/* first group ID */

	unsigned char num_groups;	/* number of groups */

	unsigned char padding[3];

	unsigned char midi_ci_version;	/* MIDI-CI support version */

	unsigned char sysex8_streams;	/* max number of sysex8 streams */

	unsigned char ui_hint;		/* user interface hint */

	unsigned int flags;		/* various info flags */

	unsigned char name[128];	/* block name string */

	unsigned char reserved[32];