1 =================
2 MIDI 2.0 on Linux
3 =================
4
5 General
6 =======
7
8 MIDI 2.0 is an extended protocol for providing
9 more fine controls over the legacy MIDI 1.0.
10 introduced 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 lega
15 - MIDI-CI for property and profile configurati
16
17 UMP is a new container format to hold all MIDI
18 2.0 protocol messages. Unlike the former byte
19 aligned, and each message can be put in a sing
20 the events up to 16 "UMP Groups", where each U
21 16 MIDI channels.
22
23 MIDI 2.0 protocol is an extended protocol to a
24 resolution and more controls over the old MIDI
25
26 MIDI-CI is a high-level protocol that can talk
27 for the flexible profiles and configurations.
28 form of special SysEx.
29
30 For Linux implementations, the kernel supports
31 the encoding/decoding of MIDI protocols on UMP
32 supported in user-space over the standard SysE
33
34 As of this writing, only USB MIDI device suppo
35 2.0 natively. The UMP support itself is prett
36 could be used by other transport layers, altho
37 implemented differently (e.g. as a ALSA sequen
38
39 The access to UMP devices are provided in two
40 rawmidi device and the access via ALSA sequenc
41
42 ALSA sequencer API was extended to allow the p
43 It's allowed to connect freely between MIDI 1.
44 clients, and the events are converted transpar
45
46
47 Kernel Configuration
48 ====================
49
50 The following new configs are added for suppor
51 `CONFIG_SND_UMP`, `CONFIG_SND_UMP_LEGACY_RAWMI
52 `CONFIG_SND_SEQ_UMP`, `CONFIG_SND_SEQ_UMP_CLIE
53 `CONFIG_SND_USB_AUDIO_MIDI_V2`. The first vis
54 `CONFIG_SND_USB_AUDIO_MIDI_V2`, and when you c
55 the core support for UMP (`CONFIG_SND_UMP`) an
56 (`CONFIG_SND_SEQ_UMP_CLIENT`) will be automati
57
58 Additionally, `CONFIG_SND_UMP_LEGACY_RAWMIDI=y
59 support for the legacy raw MIDI device for UMP
60
61
62 Rawmidi Device with USB MIDI 2.0
63 ================================
64
65 When a device supports MIDI 2.0, the USB-audio
66 the MIDI 2.0 interface (that is found always a
67 default instead of the MIDI 1.0 interface (at
68 switch back to the binding with the old MIDI 1
69 `midi2_enable=0` option to snd-usb-audio drive
70
71 The USB audio driver tries to query the UMP En
72 Block information that are provided since UMP
73 topology based on those information. When the
74 doesn't respond to the new UMP inquiries, the
75 builds the topology based on Group Terminal Bl
76 from the USB descriptor. Some device might be
77 unexpected UMP command; in such a case, pass `
78 option to snd-usb-audio driver for skipping th
79
80 When the MIDI 2.0 device is probed, the kernel
81 device for each UMP Endpoint of the device. I
82 `/dev/snd/umpC*D*` and different from the stan
83 `/dev/snd/midiC*D*` for MIDI 1.0, in order to
84 legacy applications accessing mistakenly to UM
85
86 You can read and write UMP packet data directl
87 rawmidi device. For example, reading via `hex
88 show the incoming UMP packets of the card 0 de
89 format::
90
91 % hexdump -C /dev/snd/umpC0D0
92 00000000 01 07 b0 20 00 07 b0 20 64 3c 90
93
94 Unlike the MIDI 1.0 byte stream, UMP is a 32bi
95 for reading or writing the device is also alig
96 bytes).
97
98 The 32-bit words in the UMP packet payload are
99 endianness. Transport drivers are responsible
100 from / to system endianness to required transp
101 order.
102
103 When `CONFIG_SND_UMP_LEGACY_RAWMIDI` is set, t
104 another standard raw MIDI device additionally
105 This contains 16 substreams, and each substrea
106 (0-based) UMP Group. Legacy applications can
107 group via each substream in MIDI 1.0 byte stre
108 ALSA rawmidi API, you can open the arbitrary s
109 opening `/dev/snd/midiC*D*` will end up with o
110 substream.
111
112 Each UMP Endpoint can provide the additional i
113 from the information inquired via UMP 1.1 Stre
114 2.0 descriptors. And a UMP Endpoint may conta
115 Blocks, where UMP Block is an abstraction intr
116 implementations to represent the associations
117 Block corresponds to Function Block in UMP 1.1
118 UMP 1.1 Function Block information isn't avail
119 partially from Group Terminal Block (GTB) as d
120 specifications.
121
122 The information of UMP Endpoints and UMP Block
123 file `/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
149 Note that `Groups` field shown in the proc fil
150 1-based UMP Group numbers (from-to).
151
152 Those additional UMP Endpoint and UMP Block in
153 obtained via the new ioctls `SNDRV_UMP_IOCTL_E
154 `SNDRV_UMP_IOCTL_BLOCK_INFO`, respectively.
155
156 The rawmidi name and the UMP Endpoint name are
157 in the case of USB MIDI, it's taken from `iInt
158 corresponding USB MIDI interface descriptor.
159 it's copied from `iProduct` of the USB device
160 fallback.
161
162 The Endpoint Product ID is a string field and
163 It's copied from `iSerialNumber` of the device
164
165 The protocol capabilities and the actual proto
166 `asound.h`.
167
168
169 ALSA Sequencer with USB MIDI 2.0
170 ================================
171
172 In addition to the rawmidi interfaces, ALSA se
173 supports the new UMP MIDI 2.0 device, too. No
174 client may set its MIDI version (0, 1 or 2) to
175 either the legacy, UMP MIDI 1.0 or UMP MIDI 2.
176 The first, legacy client is the one that sends
177 sequencer event as was. Meanwhile, UMP MIDI 1
178 and receive in the extended event record for U
179 seen in the new `midi_version` field of `snd_s
180
181 A UMP packet can be sent/received in a sequenc
182 specifying the new event flag bit `SNDRV_SEQ_E
183 flag is set, the event has 16 byte (128 bit) d
184 the UMP packet. Without the `SNDRV_SEQ_EVENT_
185 is treated as a legacy event as it was (with m
186 payload).
187
188 With `SNDRV_SEQ_EVENT_UMP` flag set, the type
189 event is ignored (but it should be set to 0 as
190
191 The type of each client can be seen in `/proc/
192 For 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
213 Here you can find two types of kernel clients,
214 and "UMP MIDI1" for client 20, which is a USB
215 A USB MIDI 2.0 client gives always the port 0
216 rest ports from 1 for each UMP Group (e.g. por
217 In this example, the device has three active g
218 Ext OUT), and those are exposed as sequencer p
219 The "MIDI 2.0" port is for a UMP Endpoint, and
220 other UMP Group ports is that UMP Endpoint por
221 the all ports on the device ("catch-all"), whi
222 sends only the events from the given UMP Group
223 Also, UMP groupless messages (such as the UMP
224 sent only to the UMP Endpoint port.
225
226 Note that, although each UMP sequencer client
227 ports, those ports that don't belong to any UM
228 to inactive UMP Blocks) are marked as inactive
229 in the proc outputs. In the example above, th
230 to 16 are present but not shown there.
231
232 The proc file above shows the UMP Block inform
233 entry (but with more detailed information) is
234 proc output.
235
236 When clients are connected between different M
237 are translated automatically depending on the
238 only between the legacy and the UMP MIDI 1.0/2
239 between UMP MIDI 1.0 and 2.0 types, too. For
240 `aseqdump` program on the ProtoZOA Main port i
241 give 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,
247 20:1 Note off 0, note 60,
248 20:1 Control change 0, controlle
249
250 When you run `aseqdump` in MIDI 2.0 mode, it'l
251 precision 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,
257 20:1 Note off 0, note 60,
258 20:1 Control change 0, controlle
259
260 while the data is automatically converted by A
261
262
263 Rawmidi API Extensions
264 ======================
265
266 * The additional UMP Endpoint information can
267 ioctl `SNDRV_UMP_IOCTL_ENDPOINT_INFO`. It c
268 card and device numbers, the bit flags, the
269 UMP Blocks, the name string of the endpoint,
270
271 The protocols are specified in two field, th
272 and the current protocol. Both contain the
273 MIDI protocol version (`SNDRV_UMP_EP_INFO_PR
274 `SNDRV_UMP_EP_INFO_PROTO_MIDI2`) in the uppe
275 reduction timestamp (`SNDRV_UMP_EP_INFO_PROT
276 `SNDRV_UMP_EP_INFO_PROTO_JRTS_RX`) in the lo
277
278 A UMP Endpoint may contain up to 32 UMP Bloc
279 the currently assigned blocks are shown in t
280
281 * Each UMP Block information can be obtained v
282 `SNDRV_UMP_IOCTL_BLOCK_INFO`. The block ID
283 be passed for the block to query. The recei
284 associated the direction of the block, the f
285 (0-based) and the number of groups, the name
286 etc.
287
288 The direction is either `SNDRV_UMP_DIR_INPUT
289 `SNDRV_UMP_DIR_OUTPUT` or `SNDRV_UMP_DIR_BID
290
291 * For the device supports UMP v1.1, the UMP MI
292 switched via "Stream Configuration Request"
293 status 0x05). When UMP core receives such a
294 UMP EP info and the corresponding sequencer
295
296
297 Control API Extensions
298 ======================
299
300 * The new ioctl `SNDRV_CTL_IOCTL_UMP_NEXT_DEVI
301 querying the next UMP rawmidi device, while
302 `SNDRV_CTL_IOCTL_RAWMIDI_NEXT_DEVICE` querie
303 rawmidi devices.
304
305 For setting the subdevice (substream number)
306 ioctl `SNDRV_CTL_IOCTL_RAWMIDI_PREFER_SUBDEV
307 rawmidi.
308
309 * Two new ioctls `SNDRV_CTL_IOCTL_UMP_ENDPOINT
310 `SNDRV_CTL_IOCTL_UMP_BLOCK_INFO` provide the
311 Block information of the specified UMP devic
312 without opening the actual (UMP) rawmidi dev
313 The `card` field is ignored upon inquiry, al
314 of the control interface.
315
316
317 Sequencer API Extensions
318 ========================
319
320 * `midi_version` field is added to `snd_seq_cl
321 the current MIDI version (either 0, 1 or 2)
322 When `midi_version` is 1 or 2, the alignment
323 sequencer client is also changed from the fo
324 bytes for the extended payload. The alignme
325 isn't changed, but each event size may diffe
326 bit flag below.
327
328 * `SNDRV_SEQ_EVENT_UMP` flag bit is added for
329 flags. When this bit flag is set, the seque
330 to have a larger payload of 16 bytes instead
331 bytes, and the event contains the UMP packet
332
333 * The new sequencer port type bit (`SNDRV_SEQ_
334 indicates the port being UMP-capable.
335
336 * The sequencer ports have new capability bits
337 inactive ports (`SNDRV_SEQ_PORT_CAP_INACTIVE
338 port (`SNDRV_SEQ_PORT_CAP_UMP_ENDPOINT`).
339
340 * The event conversion of ALSA sequencer clien
341 new filter bit `SNDRV_SEQ_FILTER_NO_CONVERT`
342 For example, the kernel pass-through client
343 this flag internally.
344
345 * The port information gained the new field `d
346 the direction of the port (either `SNDRV_SEQ
347 `SNDRV_SEQ_PORT_DIR_OUTPUT` or `SNDRV_SEQ_PO
348
349 * Another additional field for the port inform
350 which specifies the associated UMP Group Num
351 When it's non-zero, the UMP group field in t
352 upon delivery to the specified group (correc
353 Each sequencer port is supposed to set this
354 specific to a certain UMP group.
355
356 * Each client may set the additional event fil
357 `group_filter` bitmap. The filter consists
358 Group numbers. For example, when the bit 1
359 Group 1 (i.e. the very first group) are filt
360 The bit 0 is used for filtering UMP grouples
361
362 * Two new ioctls are added for UMP-capable cli
363 `SNDRV_SEQ_IOCTL_GET_CLIENT_UMP_INFO` and
364 `SNDRV_SEQ_IOCTL_SET_CLIENT_UMP_INFO`. They
365 either `snd_ump_endpoint_info` or `snd_ump_b
366 associated with the sequencer client. The U
367 those information from the underlying UMP ra
368 user-space client may provide its own data v
369 For an Endpoint data, pass 0 to the `type` f
370 data, pass the block number + 1 to the `type
371 Setting the data for a kernel client shall r
372
373 * With UMP 1.1, Function Block information may
374 dynamically. When the update of Function Bl
375 device, ALSA sequencer core changes the corr
376 name and attributes accordingly, and notifie
377 announcement to the ALSA sequencer system po
378 normal port change notification.
379
380
381 MIDI2 USB Gadget Function Driver
382 ================================
383
384 The latest kernel contains the support for USB
385 function driver, which can be used for prototy
386 2.0 features.
387
388 `CONFIG_USB_GADGET`, `CONFIG_USB_CONFIGFS` and
389 `CONFIG_USB_CONFIGFS_F_MIDI2` need to be enabl
390 driver.
391
392 In addition, for using a gadget driver, you ne
393 In the example below, we use `dummy_hcd` drive
394 `CONFIG_USB_DUMMY_HCD`) that is available on P
395 purpose. There are other UDC drivers dependin
396 those can be used for a real device, instead,
397
398 At first, on a system to run the gadget, load
399
400 % modprobe libcomposite
401
402 and you'll have `usb_gadget` subdirectory unde
403 (typically `/sys/kernel/config` on modern OS).
404 instance and add configurations there, for exa
405
406 % cd /sys/kernel/config
407 % mkdir usb_gadget/g1
408
409 % cd usb_gadget/g1
410 % mkdir configs/c.1
411 % mkdir functions/midi2.usb0
412
413 % echo 0x0004 > idProduct
414 % echo 0x17b3 > idVendor
415 % mkdir strings/0x409
416 % echo "ACME Enterprises" > strings/0x409/ma
417 % echo "ACMESynth" > strings/0x409/product
418 % echo "ABCD12345" > strings/0x409/serialnum
419
420 % mkdir configs/c.1/strings/0x409
421 % echo "Monosynth" > configs/c.1/strings/0x4
422 % echo 120 > configs/c.1/MaxPower
423
424 At this point, there must be a subdirectory `e
425 configuration for a UMP Endpoint. You can fil
426 information like::
427
428 % echo "ACMESynth" > functions/midi2.usb0/if
429 % echo "ACMESynth" > functions/midi2.usb0/ep
430 % echo "ABCD12345" > functions/midi2.usb0/ep
431 % echo 0x0123 > functions/midi2.usb0/ep.0/fa
432 % echo 0x4567 > functions/midi2.usb0/ep.0/mo
433 % echo 0x123456 > functions/midi2.usb0/ep.0/
434 % echo 0x12345678 > functions/midi2.usb0/ep.
435
436 The default MIDI protocol can be set either 1
437
438 % echo 2 > functions/midi2.usb0/ep.0/protoco
439
440 And, you can find a subdirectory `block.0` und
441 subdirectory. This defines the Function Block
442
443 % echo "Monosynth" > functions/midi2.usb0/ep
444 % echo 0 > functions/midi2.usb0/ep.0/block.0
445 % echo 1 > functions/midi2.usb0/ep.0/block.0
446
447 Finally, link the configuration and enable it:
448
449 % ln -s functions/midi2.usb0 configs/c.1
450 % echo dummy_udc.0 > UDC
451
452 where `dummy_udc.0` is an example case and it
453 system. You can find the UDC instances in `/s
454 the found name instead::
455
456 % ls /sys/class/udc
457 dummy_udc.0
458
459 Now, the MIDI 2.0 gadget device is enabled, an
460 creates a new sound card instance containing a
461 `f_midi2` driver::
462
463 % cat /proc/asound/cards
464 ....
465 1 [Gadget ]: f_midi2 - MIDI 2.0 Gadg
466 MIDI 2.0 Gadget
467
468 And on the connected host, a similar card shou
469 the card and device names given in the configf
470
471 % cat /proc/asound/cards
472 ....
473 2 [ACMESynth ]: USB-Audio - ACMESynth
474 ACME Enterprises ACMESy
475
476 You can play a MIDI file on the gadget side::
477
478 % aplaymidi -p 20:1 to_host.mid
479
480 and this will appear as an input from a MIDI d
481 host::
482
483 % aseqdump -p 20:0 -u 2
484
485 Vice versa, a playback on the connected host w
486 the gadget, too.
487
488 Each Function Block may have different directi
489 specified via `direction` and `ui_hint` attrib
490 Passing `1` is for input-only, `2` for out-onl
491 bidirectional (the default value). For exampl
492
493 % echo 2 > functions/midi2.usb0/ep.0/block.0
494 % echo 2 > functions/midi2.usb0/ep.0/block.0
495
496 When you need more than one Function Blocks, y
497 subdirectories `block.1`, `block.2`, etc dynam
498 them in the configuration procedure above befo
499 For example, to create a second Function Block
500
501 % mkdir functions/midi2.usb0/ep.0/block.1
502 % echo "Keyboard" > functions/midi2.usb0/ep.
503 % echo 1 > functions/midi2.usb0/ep.0/block.1
504 % echo 1 > functions/midi2.usb0/ep.0/block.1
505 % echo 1 > functions/midi2.usb0/ep.0/block.1
506 % echo 1 > functions/midi2.usb0/ep.0/block.1
507
508 The `block.*` subdirectories can be removed dy
509 for `block.0` which is persistent).
510
511 For assigning a Function Block for MIDI 1.0 I/
512 attribute. 1 is for MIDI 1.0, and 2 is for MI
513 connection::
514
515 % echo 2 > functions/midi2.usb0/ep.0/block.1
516
517 For disabling the processing of UMP Stream mes
518 driver, pass `0` to `process_ump` attribute in
519
520 % echo 0 > functions/midi2.usb0/process_ump
521
522 The MIDI 1.0 interface at altset 0 is supporte
523 too. When MIDI 1.0 interface is selected by t
524 UMP I/O on the gadget is translated from/to US
525 accordingly while the gadget driver keeps comm
526 user-space over UMP rawmidi.
527
528 MIDI 1.0 ports are set up from the config in e
529 For example::
530
531 % echo 0 > functions/midi2.usb0/ep.0/block.0
532 % echo 1 > functions/midi2.usb0/ep.0/block.0
533
534 The configuration above will enable the Group
535 1.0 interface. Note that those groups must be
536 for the Function Block itself.
537
538 The gadget driver supports more than one UMP E
539 Similarly like the Function Blocks, you can cr
540 `ep.1` (but under the card top-level config) t
541
542 % mkdir functions/midi2.usb0/ep.1
543
544 and create a new Function Block there. For ex
545 Groups for the Function Block of this new Endp
546
547 % mkdir functions/midi2.usb0/ep.1/block.0
548 % echo 4 > functions/midi2.usb0/ep.1/block.0
549
550 Now, you'll have 4 rawmidi devices in total: t
551 rawmidi devices for Endpoint 0 and Endpoint 1,
552 legacy MIDI 1.0 rawmidi devices corresponding
553
554 The current altsetting on the gadget can be in
555 element "Operation Mode" with `RAWMIDI` iface.
556 via `amixer` program running on the gadget hos
557
558 % amixer -c1 cget iface=RAWMIDI,name='Operat
559 ; type=INTEGER,access=r--v----,values=1,min=
560 : values=2
561
562 The value (shown in the second returned line w
563 indicates 1 for MIDI 1.0 (altset 0), 2 for MID
564 for unset.
565
566 As of now, the configurations can't be changed
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.