1=================
2MIDI 2.0 on Linux
3=================
4
5General
6=======
7
8MIDI 2.0 is an extended protocol for providing higher resolutions and
9more fine controls over the legacy MIDI 1.0.  The fundamental changes
10introduced for supporting MIDI 2.0 are:
11
12- Support of Universal MIDI Packet (UMP)
13- Support of MIDI 2.0 protocol messages
14- Transparent conversions between UMP and legacy MIDI 1.0 byte stream
15- MIDI-CI for property and profile configurations
16
17UMP is a new container format to hold all MIDI protocol 1.0 and MIDI
182.0 protocol messages.  Unlike the former byte stream, it's 32bit
19aligned, and each message can be put in a single packet.  UMP can send
20the events up to 16 "UMP Groups", where each UMP Group contain up to
2116 MIDI channels.
22
23MIDI 2.0 protocol is an extended protocol to achieve the higher
24resolution and more controls over the old MIDI 1.0 protocol.
25
26MIDI-CI is a high-level protocol that can talk with the MIDI device
27for the flexible profiles and configurations.  It's represented in the
28form of special SysEx.
29
30For Linux implementations, the kernel supports the UMP transport and
31the encoding/decoding of MIDI protocols on UMP, while MIDI-CI is
32supported in user-space over the standard SysEx.
33
34As of this writing, only USB MIDI device supports the UMP and Linux
352.0 natively.  The UMP support itself is pretty generic, hence it
36could be used by other transport layers, although it could be
37implemented differently (e.g. as a ALSA sequencer client), too.
38
39The access to UMP devices are provided in two ways: the access via
40rawmidi device and the access via ALSA sequencer API.
41
42ALSA sequencer API was extended to allow the payload of UMP packets.
43It's allowed to connect freely between MIDI 1.0 and MIDI 2.0 sequencer
44clients, and the events are converted transparently.
45
46
47Kernel Configuration
48====================
49
50The following new configs are added for supporting MIDI 2.0:
51`CONFIG_SND_UMP`, `CONFIG_SND_UMP_LEGACY_RAWMIDI`,
52`CONFIG_SND_SEQ_UMP`, `CONFIG_SND_SEQ_UMP_CLIENT`, and
53`CONFIG_SND_USB_AUDIO_MIDI_V2`.  The first visible one is
54`CONFIG_SND_USB_AUDIO_MIDI_V2`, and when you choose it (to set `=y`),
55the core support for UMP (`CONFIG_SND_UMP`) and the sequencer binding
56(`CONFIG_SND_SEQ_UMP_CLIENT`) will be automatically selected.
57
58Additionally, `CONFIG_SND_UMP_LEGACY_RAWMIDI=y` will enable the
59support for the legacy raw MIDI device for UMP Endpoints.
60
61
62Rawmidi Device with USB MIDI 2.0
63================================
64
65When a device supports MIDI 2.0, the USB-audio driver probes and uses
66the MIDI 2.0 interface (that is found always at the altset 1) as
67default instead of the MIDI 1.0 interface (at altset 0).  You can
68switch back to the binding with the old MIDI 1.0 interface by passing
69`midi2_enable=0` option to snd-usb-audio driver module, too.
70
71The USB audio driver tries to query the UMP Endpoint and UMP Function
72Block information that are provided since UMP v1.1, and builds up the
73topology based on those information.  When the device is older and
74doesn't respond to the new UMP inquiries, the driver falls back and
75builds the topology based on Group Terminal Block (GTB) information
76from the USB descriptor.  Some device might be screwed up by the
77unexpected UMP command; in such a case, pass `midi2_probe=0` option to
78snd-usb-audio driver for skipping the UMP v1.1 inquiries.
79
80When the MIDI 2.0 device is probed, the kernel creates a rawmidi
81device for each UMP Endpoint of the device.  Its device name is
82`/dev/snd/umpC*D*` and different from the standard rawmidi device name
83`/dev/snd/midiC*D*` for MIDI 1.0, in order to avoid confusing the
84legacy applications accessing mistakenly to UMP devices.
85
86You can read and write UMP packet data directly from/to this UMP
87rawmidi device.  For example, reading via `hexdump` like below will
88show the incoming UMP packets of the card 0 device 0 in the hex
89format::
90
91  % hexdump -C /dev/snd/umpC0D0
92  00000000  01 07 b0 20 00 07 b0 20  64 3c 90 20 64 3c 80 20  |... ... d<. d<. |
93
94Unlike the MIDI 1.0 byte stream, UMP is a 32bit packet, and the size
95for reading or writing the device is also aligned to 32bit (which is 4
96bytes).
97
98The 32-bit words in the UMP packet payload are always in CPU native
99endianness.  Transport drivers are responsible to convert UMP words
100from / to system endianness to required transport endianness / byte
101order.
102
103When `CONFIG_SND_UMP_LEGACY_RAWMIDI` is set, the driver creates
104another standard raw MIDI device additionally as `/dev/snd/midiC*D*`.
105This contains 16 substreams, and each substream corresponds to a
106(0-based) UMP Group.  Legacy applications can access to the specified
107group via each substream in MIDI 1.0 byte stream format.  With the
108ALSA rawmidi API, you can open the arbitrary substream, while just
109opening `/dev/snd/midiC*D*` will end up with opening the first
110substream.
111
112Each UMP Endpoint can provide the additional information, constructed
113from the information inquired via UMP 1.1 Stream messages or USB MIDI
1142.0 descriptors.  And a UMP Endpoint may contain one or more UMP
115Blocks, where UMP Block is an abstraction introduced in the ALSA UMP
116implementations to represent the associations among UMP Groups.  UMP
117Block corresponds to Function Block in UMP 1.1 specification.  When
118UMP 1.1 Function Block information isn't available, it's filled
119partially from Group Terminal Block (GTB) as defined in USB MIDI 2.0
120specifications.
121
122The information of UMP Endpoints and UMP Blocks are found in the proc
123file `/proc/asound/card*/midi*`.  For example::
124
125  % cat /proc/asound/card1/midi0
126  ProtoZOA MIDI
127
128  Type: UMP
129  EP Name: ProtoZOA
130  EP Product ID: ABCD12345678
131  UMP Version: 0x0000
132  Protocol Caps: 0x00000100
133  Protocol: 0x00000100
134  Num Blocks: 3
135
136  Block 0 (ProtoZOA Main)
137    Direction: bidirection
138    Active: Yes
139    Groups: 1-1
140    Is MIDI1: No
141
142  Block 1 (ProtoZOA Ext IN)
143    Direction: output
144    Active: Yes
145    Groups: 2-2
146    Is MIDI1: Yes (Low Speed)
147  ....
148
149Note that `Groups` field shown in the proc file above indicates the
1501-based UMP Group numbers (from-to).
151
152Those additional UMP Endpoint and UMP Block information can be
153obtained via the new ioctls `SNDRV_UMP_IOCTL_ENDPOINT_INFO` and
154`SNDRV_UMP_IOCTL_BLOCK_INFO`, respectively.
155
156The rawmidi name and the UMP Endpoint name are usually identical, and
157in the case of USB MIDI, it's taken from `iInterface` of the
158corresponding USB MIDI interface descriptor.  If it's not provided,
159it's copied from `iProduct` of the USB device descriptor as a
160fallback.
161
162The Endpoint Product ID is a string field and supposed to be unique.
163It's copied from `iSerialNumber` of the device for USB MIDI.
164
165The protocol capabilities and the actual protocol bits are defined in
166`asound.h`.
167
168
169ALSA Sequencer with USB MIDI 2.0
170================================
171
172In addition to the rawmidi interfaces, ALSA sequencer interface
173supports the new UMP MIDI 2.0 device, too.  Now, each ALSA sequencer
174client may set its MIDI version (0, 1 or 2) to declare itself being
175either the legacy, UMP MIDI 1.0 or UMP MIDI 2.0 device, respectively.
176The first, legacy client is the one that sends/receives the old
177sequencer event as was.  Meanwhile, UMP MIDI 1.0 and 2.0 clients send
178and receive in the extended event record for UMP.  The MIDI version is
179seen in the new `midi_version` field of `snd_seq_client_info`.
180
181A UMP packet can be sent/received in a sequencer event embedded by
182specifying the new event flag bit `SNDRV_SEQ_EVENT_UMP`.  When this
183flag is set, the event has 16 byte (128 bit) data payload for holding
184the UMP packet.  Without the `SNDRV_SEQ_EVENT_UMP` bit flag, the event
185is treated as a legacy event as it was (with max 12 byte data
186payload).
187
188With `SNDRV_SEQ_EVENT_UMP` flag set, the type field of a UMP sequencer
189event is ignored (but it should be set to 0 as default).
190
191The type of each client can be seen in `/proc/asound/seq/clients`.
192For example::
193
194  % cat /proc/asound/seq/clients
195  Client info
196    cur  clients : 3
197  ....
198  Client  14 : "Midi Through" [Kernel Legacy]
199    Port   0 : "Midi Through Port-0" (RWe-)
200  Client  20 : "ProtoZOA" [Kernel UMP MIDI1]
201    UMP Endpoint: ProtoZOA
202    UMP Block 0: ProtoZOA Main [Active]
203      Groups: 1-1
204    UMP Block 1: ProtoZOA Ext IN [Active]
205      Groups: 2-2
206    UMP Block 2: ProtoZOA Ext OUT [Active]
207      Groups: 3-3
208    Port   0 : "MIDI 2.0" (RWeX) [In/Out]
209    Port   1 : "ProtoZOA Main" (RWeX) [In/Out]
210    Port   2 : "ProtoZOA Ext IN" (-We-) [Out]
211    Port   3 : "ProtoZOA Ext OUT" (R-e-) [In]
212
213Here you can find two types of kernel clients, "Legacy" for client 14,
214and "UMP MIDI1" for client 20, which is a USB MIDI 2.0 device.
215A USB MIDI 2.0 client gives always the port 0 as "MIDI 2.0" and the
216rest ports from 1 for each UMP Group (e.g. port 1 for Group 1).
217In this example, the device has three active groups (Main, Ext IN and
218Ext OUT), and those are exposed as sequencer ports from 1 to 3.
219The "MIDI 2.0" port is for a UMP Endpoint, and its difference from
220other UMP Group ports is that UMP Endpoint port sends the events from
221the all ports on the device ("catch-all"), while each UMP Group port
222sends only the events from the given UMP Group.
223Also, UMP groupless messages (such as the UMP message type 0x0f) are
224sent only to the UMP Endpoint port.
225
226Note that, although each UMP sequencer client usually creates 16
227ports, those ports that don't belong to any UMP Blocks (or belonging
228to inactive UMP Blocks) are marked as inactive, and they don't appear
229in the proc outputs.  In the example above, the sequencer ports from 4
230to 16 are present but not shown there.
231
232The proc file above shows the UMP Block information, too.  The same
233entry (but with more detailed information) is found in the rawmidi
234proc output.
235
236When clients are connected between different MIDI versions, the events
237are translated automatically depending on the client's version, not
238only between the legacy and the UMP MIDI 1.0/2.0 types, but also
239between UMP MIDI 1.0 and 2.0 types, too.  For example, running
240`aseqdump` program on the ProtoZOA Main port in the legacy mode will
241give you the output like::
242
243  % aseqdump -p 20:1
244  Waiting for data. Press Ctrl+C to end.
245  Source  Event                  Ch  Data
246   20:1   Note on                 0, note 60, velocity 100
247   20:1   Note off                0, note 60, velocity 100
248   20:1   Control change          0, controller 11, value 4
249
250When you run `aseqdump` in MIDI 2.0 mode, it'll receive the high
251precision data like::
252
253  % aseqdump -u 2 -p 20:1
254  Waiting for data. Press Ctrl+C to end.
255  Source  Event                  Ch  Data
256   20:1   Note on                 0, note 60, velocity 0xc924, attr type = 0, data = 0x0
257   20:1   Note off                0, note 60, velocity 0xc924, attr type = 0, data = 0x0
258   20:1   Control change          0, controller 11, value 0x2000000
259
260while the data is automatically converted by ALSA sequencer core.
261
262
263Rawmidi API Extensions
264======================
265
266* The additional UMP Endpoint information can be obtained via the new
267  ioctl `SNDRV_UMP_IOCTL_ENDPOINT_INFO`.  It contains the associated
268  card and device numbers, the bit flags, the protocols, the number of
269  UMP Blocks, the name string of the endpoint, etc.
270
271  The protocols are specified in two field, the protocol capabilities
272  and the current protocol.  Both contain the bit flags specifying the
273  MIDI protocol version (`SNDRV_UMP_EP_INFO_PROTO_MIDI1` or
274  `SNDRV_UMP_EP_INFO_PROTO_MIDI2`) in the upper byte and the jitter
275  reduction timestamp (`SNDRV_UMP_EP_INFO_PROTO_JRTS_TX` and
276  `SNDRV_UMP_EP_INFO_PROTO_JRTS_RX`) in the lower byte.
277
278  A UMP Endpoint may contain up to 32 UMP Blocks, and the number of
279  the currently assigned blocks are shown in the Endpoint information.
280
281* Each UMP Block information can be obtained via another new ioctl
282  `SNDRV_UMP_IOCTL_BLOCK_INFO`.  The block ID number (0-based) has to
283  be passed for the block to query.  The received data contains the
284  associated the direction of the block, the first associated group ID
285  (0-based) and the number of groups, the name string of the block,
286  etc.
287
288  The direction is either `SNDRV_UMP_DIR_INPUT`,
289  `SNDRV_UMP_DIR_OUTPUT` or `SNDRV_UMP_DIR_BIDIRECTION`.
290
291* For the device supports UMP v1.1, the UMP MIDI protocol can be
292  switched via "Stream Configuration Request" message (UMP type 0x0f,
293  status 0x05).  When UMP core receives such a message, it updates the
294  UMP EP info and the corresponding sequencer clients as well.
295
296
297Control API Extensions
298======================
299
300* The new ioctl `SNDRV_CTL_IOCTL_UMP_NEXT_DEVICE` is introduced for
301  querying the next UMP rawmidi device, while the existing ioctl
302  `SNDRV_CTL_IOCTL_RAWMIDI_NEXT_DEVICE` queries only the legacy
303  rawmidi devices.
304
305  For setting the subdevice (substream number) to be opened, use the
306  ioctl `SNDRV_CTL_IOCTL_RAWMIDI_PREFER_SUBDEVICE` like the normal
307  rawmidi.
308
309* Two new ioctls `SNDRV_CTL_IOCTL_UMP_ENDPOINT_INFO` and
310  `SNDRV_CTL_IOCTL_UMP_BLOCK_INFO` provide the UMP Endpoint and UMP
311  Block information of the specified UMP device via ALSA control API
312  without opening the actual (UMP) rawmidi device.
313  The `card` field is ignored upon inquiry, always tied with the card
314  of the control interface.
315
316
317Sequencer API Extensions
318========================
319
320* `midi_version` field is added to `snd_seq_client_info` to indicate
321  the current MIDI version (either 0, 1 or 2) of each client.
322  When `midi_version` is 1 or 2, the alignment of read from a UMP
323  sequencer client is also changed from the former 28 bytes to 32
324  bytes for the extended payload.  The alignment size for the write
325  isn't changed, but each event size may differ depending on the new
326  bit flag below.
327
328* `SNDRV_SEQ_EVENT_UMP` flag bit is added for each sequencer event
329  flags.  When this bit flag is set, the sequencer event is extended
330  to have a larger payload of 16 bytes instead of the legacy 12
331  bytes, and the event contains the UMP packet in the payload.
332
333* The new sequencer port type bit (`SNDRV_SEQ_PORT_TYPE_MIDI_UMP`)
334  indicates the port being UMP-capable.
335
336* The sequencer ports have new capability bits to indicate the
337  inactive ports (`SNDRV_SEQ_PORT_CAP_INACTIVE`) and the UMP Endpoint
338  port (`SNDRV_SEQ_PORT_CAP_UMP_ENDPOINT`).
339
340* The event conversion of ALSA sequencer clients can be suppressed the
341  new filter bit `SNDRV_SEQ_FILTER_NO_CONVERT` set to the client info.
342  For example, the kernel pass-through client (`snd-seq-dummy`) sets
343  this flag internally.
344
345* The port information gained the new field `direction` to indicate
346  the direction of the port (either `SNDRV_SEQ_PORT_DIR_INPUT`,
347  `SNDRV_SEQ_PORT_DIR_OUTPUT` or `SNDRV_SEQ_PORT_DIR_BIDIRECTION`).
348
349* Another additional field for the port information is `ump_group`
350  which specifies the associated UMP Group Number (1-based).
351  When it's non-zero, the UMP group field in the UMP packet updated
352  upon delivery to the specified group (corrected to be 0-based).
353  Each sequencer port is supposed to set this field if it's a port to
354  specific to a certain UMP group.
355
356* Each client may set the additional event filter for UMP Groups in
357  `group_filter` bitmap.  The filter consists of bitmap from 1-based
358  Group numbers.  For example, when the bit 1 is set, messages from
359  Group 1 (i.e. the very first group) are filtered and not delivered.
360  The bit 0 is used for filtering UMP groupless messages.
361
362* Two new ioctls are added for UMP-capable clients:
363  `SNDRV_SEQ_IOCTL_GET_CLIENT_UMP_INFO` and
364  `SNDRV_SEQ_IOCTL_SET_CLIENT_UMP_INFO`.  They are used to get and set
365  either `snd_ump_endpoint_info` or `snd_ump_block_info` data
366  associated with the sequencer client.  The USB MIDI driver provides
367  those information from the underlying UMP rawmidi, while a
368  user-space client may provide its own data via `*_SET` ioctl.
369  For an Endpoint data, pass 0 to the `type` field, while for a Block
370  data, pass the block number + 1 to the `type` field.
371  Setting the data for a kernel client shall result in an error.
372
373* With UMP 1.1, Function Block information may be changed
374  dynamically.  When the update of Function Block is received from the
375  device, ALSA sequencer core changes the corresponding sequencer port
376  name and attributes accordingly, and notifies the changes via the
377  announcement to the ALSA sequencer system port, similarly like the
378  normal port change notification.
379