567 lines · plain
1=================2MIDI 2.0 on Linux3=================4 5General6=======7 8MIDI 2.0 is an extended protocol for providing higher resolutions and9more fine controls over the legacy MIDI 1.0. The fundamental changes10introduced for supporting MIDI 2.0 are:11 12- Support of Universal MIDI Packet (UMP)13- Support of MIDI 2.0 protocol messages14- Transparent conversions between UMP and legacy MIDI 1.0 byte stream15- MIDI-CI for property and profile configurations16 17UMP is a new container format to hold all MIDI protocol 1.0 and MIDI182.0 protocol messages. Unlike the former byte stream, it's 32bit19aligned, and each message can be put in a single packet. UMP can send20the events up to 16 "UMP Groups", where each UMP Group contain up to2116 MIDI channels.22 23MIDI 2.0 protocol is an extended protocol to achieve the higher24resolution and more controls over the old MIDI 1.0 protocol.25 26MIDI-CI is a high-level protocol that can talk with the MIDI device27for the flexible profiles and configurations. It's represented in the28form of special SysEx.29 30For Linux implementations, the kernel supports the UMP transport and31the encoding/decoding of MIDI protocols on UMP, while MIDI-CI is32supported in user-space over the standard SysEx.33 34As of this writing, only USB MIDI device supports the UMP and Linux352.0 natively. The UMP support itself is pretty generic, hence it36could be used by other transport layers, although it could be37implemented differently (e.g. as a ALSA sequencer client), too.38 39The access to UMP devices are provided in two ways: the access via40rawmidi 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 sequencer44clients, and the events are converted transparently.45 46 47Kernel Configuration48====================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`, and53`CONFIG_SND_USB_AUDIO_MIDI_V2`. The first visible one is54`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 binding56(`CONFIG_SND_SEQ_UMP_CLIENT`) will be automatically selected.57 58Additionally, `CONFIG_SND_UMP_LEGACY_RAWMIDI=y` will enable the59support for the legacy raw MIDI device for UMP Endpoints.60 61 62Rawmidi Device with USB MIDI 2.063================================64 65When a device supports MIDI 2.0, the USB-audio driver probes and uses66the MIDI 2.0 interface (that is found always at the altset 1) as67default instead of the MIDI 1.0 interface (at altset 0). You can68switch back to the binding with the old MIDI 1.0 interface by passing69`midi2_enable=0` option to snd-usb-audio driver module, too.70 71The USB audio driver tries to query the UMP Endpoint and UMP Function72Block information that are provided since UMP v1.1, and builds up the73topology based on those information. When the device is older and74doesn't respond to the new UMP inquiries, the driver falls back and75builds the topology based on Group Terminal Block (GTB) information76from the USB descriptor. Some device might be screwed up by the77unexpected UMP command; in such a case, pass `midi2_ump_probe=0`78option to snd-usb-audio driver for skipping the UMP v1.1 inquiries.79 80When the MIDI 2.0 device is probed, the kernel creates a rawmidi81device for each UMP Endpoint of the device. Its device name is82`/dev/snd/umpC*D*` and different from the standard rawmidi device name83`/dev/snd/midiC*D*` for MIDI 1.0, in order to avoid confusing the84legacy applications accessing mistakenly to UMP devices.85 86You can read and write UMP packet data directly from/to this UMP87rawmidi device. For example, reading via `hexdump` like below will88show the incoming UMP packets of the card 0 device 0 in the hex89format::90 91 % hexdump -C /dev/snd/umpC0D092 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 size95for reading or writing the device is also aligned to 32bit (which is 496bytes).97 98The 32-bit words in the UMP packet payload are always in CPU native99endianness. Transport drivers are responsible to convert UMP words100from / to system endianness to required transport endianness / byte101order.102 103When `CONFIG_SND_UMP_LEGACY_RAWMIDI` is set, the driver creates104another standard raw MIDI device additionally as `/dev/snd/midiC*D*`.105This contains 16 substreams, and each substream corresponds to a106(0-based) UMP Group. Legacy applications can access to the specified107group via each substream in MIDI 1.0 byte stream format. With the108ALSA rawmidi API, you can open the arbitrary substream, while just109opening `/dev/snd/midiC*D*` will end up with opening the first110substream.111 112Each UMP Endpoint can provide the additional information, constructed113from the information inquired via UMP 1.1 Stream messages or USB MIDI1142.0 descriptors. And a UMP Endpoint may contain one or more UMP115Blocks, where UMP Block is an abstraction introduced in the ALSA UMP116implementations to represent the associations among UMP Groups. UMP117Block corresponds to Function Block in UMP 1.1 specification. When118UMP 1.1 Function Block information isn't available, it's filled119partially from Group Terminal Block (GTB) as defined in USB MIDI 2.0120specifications.121 122The information of UMP Endpoints and UMP Blocks are found in the proc123file `/proc/asound/card*/midi*`. For example::124 125 % cat /proc/asound/card1/midi0126 ProtoZOA MIDI127 128 Type: UMP129 EP Name: ProtoZOA130 EP Product ID: ABCD12345678131 UMP Version: 0x0000132 Protocol Caps: 0x00000100133 Protocol: 0x00000100134 Num Blocks: 3135 136 Block 0 (ProtoZOA Main)137 Direction: bidirection138 Active: Yes139 Groups: 1-1140 Is MIDI1: No141 142 Block 1 (ProtoZOA Ext IN)143 Direction: output144 Active: Yes145 Groups: 2-2146 Is MIDI1: Yes (Low Speed)147 ....148 149Note that `Groups` field shown in the proc file above indicates the1501-based UMP Group numbers (from-to).151 152Those additional UMP Endpoint and UMP Block information can be153obtained via the new ioctls `SNDRV_UMP_IOCTL_ENDPOINT_INFO` and154`SNDRV_UMP_IOCTL_BLOCK_INFO`, respectively.155 156The rawmidi name and the UMP Endpoint name are usually identical, and157in the case of USB MIDI, it's taken from `iInterface` of the158corresponding USB MIDI interface descriptor. If it's not provided,159it's copied from `iProduct` of the USB device descriptor as a160fallback.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 in166`asound.h`.167 168 169ALSA Sequencer with USB MIDI 2.0170================================171 172In addition to the rawmidi interfaces, ALSA sequencer interface173supports the new UMP MIDI 2.0 device, too. Now, each ALSA sequencer174client may set its MIDI version (0, 1 or 2) to declare itself being175either the legacy, UMP MIDI 1.0 or UMP MIDI 2.0 device, respectively.176The first, legacy client is the one that sends/receives the old177sequencer event as was. Meanwhile, UMP MIDI 1.0 and 2.0 clients send178and receive in the extended event record for UMP. The MIDI version is179seen in the new `midi_version` field of `snd_seq_client_info`.180 181A UMP packet can be sent/received in a sequencer event embedded by182specifying the new event flag bit `SNDRV_SEQ_EVENT_UMP`. When this183flag is set, the event has 16 byte (128 bit) data payload for holding184the UMP packet. Without the `SNDRV_SEQ_EVENT_UMP` bit flag, the event185is treated as a legacy event as it was (with max 12 byte data186payload).187 188With `SNDRV_SEQ_EVENT_UMP` flag set, the type field of a UMP sequencer189event 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/clients195 Client info196 cur clients : 3197 ....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: ProtoZOA202 UMP Block 0: ProtoZOA Main [Active]203 Groups: 1-1204 UMP Block 1: ProtoZOA Ext IN [Active]205 Groups: 2-2206 UMP Block 2: ProtoZOA Ext OUT [Active]207 Groups: 3-3208 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 the216rest 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 and218Ext 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 from220other UMP Group ports is that UMP Endpoint port sends the events from221the all ports on the device ("catch-all"), while each UMP Group port222sends only the events from the given UMP Group.223Also, UMP groupless messages (such as the UMP message type 0x0f) are224sent only to the UMP Endpoint port.225 226Note that, although each UMP sequencer client usually creates 16227ports, those ports that don't belong to any UMP Blocks (or belonging228to inactive UMP Blocks) are marked as inactive, and they don't appear229in the proc outputs. In the example above, the sequencer ports from 4230to 16 are present but not shown there.231 232The proc file above shows the UMP Block information, too. The same233entry (but with more detailed information) is found in the rawmidi234proc output.235 236When clients are connected between different MIDI versions, the events237are translated automatically depending on the client's version, not238only between the legacy and the UMP MIDI 1.0/2.0 types, but also239between UMP MIDI 1.0 and 2.0 types, too. For example, running240`aseqdump` program on the ProtoZOA Main port in the legacy mode will241give you the output like::242 243 % aseqdump -p 20:1244 Waiting for data. Press Ctrl+C to end.245 Source Event Ch Data246 20:1 Note on 0, note 60, velocity 100247 20:1 Note off 0, note 60, velocity 100248 20:1 Control change 0, controller 11, value 4249 250When you run `aseqdump` in MIDI 2.0 mode, it'll receive the high251precision data like::252 253 % aseqdump -u 2 -p 20:1254 Waiting for data. Press Ctrl+C to end.255 Source Event Ch Data256 20:1 Note on 0, note 60, velocity 0xc924, attr type = 0, data = 0x0257 20:1 Note off 0, note 60, velocity 0xc924, attr type = 0, data = 0x0258 20:1 Control change 0, controller 11, value 0x2000000259 260while the data is automatically converted by ALSA sequencer core.261 262 263Rawmidi API Extensions264======================265 266* The additional UMP Endpoint information can be obtained via the new267 ioctl `SNDRV_UMP_IOCTL_ENDPOINT_INFO`. It contains the associated268 card and device numbers, the bit flags, the protocols, the number of269 UMP Blocks, the name string of the endpoint, etc.270 271 The protocols are specified in two field, the protocol capabilities272 and the current protocol. Both contain the bit flags specifying the273 MIDI protocol version (`SNDRV_UMP_EP_INFO_PROTO_MIDI1` or274 `SNDRV_UMP_EP_INFO_PROTO_MIDI2`) in the upper byte and the jitter275 reduction timestamp (`SNDRV_UMP_EP_INFO_PROTO_JRTS_TX` and276 `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 of279 the currently assigned blocks are shown in the Endpoint information.280 281* Each UMP Block information can be obtained via another new ioctl282 `SNDRV_UMP_IOCTL_BLOCK_INFO`. The block ID number (0-based) has to283 be passed for the block to query. The received data contains the284 associated the direction of the block, the first associated group ID285 (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 be292 switched via "Stream Configuration Request" message (UMP type 0x0f,293 status 0x05). When UMP core receives such a message, it updates the294 UMP EP info and the corresponding sequencer clients as well.295 296 297Control API Extensions298======================299 300* The new ioctl `SNDRV_CTL_IOCTL_UMP_NEXT_DEVICE` is introduced for301 querying the next UMP rawmidi device, while the existing ioctl302 `SNDRV_CTL_IOCTL_RAWMIDI_NEXT_DEVICE` queries only the legacy303 rawmidi devices.304 305 For setting the subdevice (substream number) to be opened, use the306 ioctl `SNDRV_CTL_IOCTL_RAWMIDI_PREFER_SUBDEVICE` like the normal307 rawmidi.308 309* Two new ioctls `SNDRV_CTL_IOCTL_UMP_ENDPOINT_INFO` and310 `SNDRV_CTL_IOCTL_UMP_BLOCK_INFO` provide the UMP Endpoint and UMP311 Block information of the specified UMP device via ALSA control API312 without opening the actual (UMP) rawmidi device.313 The `card` field is ignored upon inquiry, always tied with the card314 of the control interface.315 316 317Sequencer API Extensions318========================319 320* `midi_version` field is added to `snd_seq_client_info` to indicate321 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 UMP323 sequencer client is also changed from the former 28 bytes to 32324 bytes for the extended payload. The alignment size for the write325 isn't changed, but each event size may differ depending on the new326 bit flag below.327 328* `SNDRV_SEQ_EVENT_UMP` flag bit is added for each sequencer event329 flags. When this bit flag is set, the sequencer event is extended330 to have a larger payload of 16 bytes instead of the legacy 12331 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 the337 inactive ports (`SNDRV_SEQ_PORT_CAP_INACTIVE`) and the UMP Endpoint338 port (`SNDRV_SEQ_PORT_CAP_UMP_ENDPOINT`).339 340* The event conversion of ALSA sequencer clients can be suppressed the341 new filter bit `SNDRV_SEQ_FILTER_NO_CONVERT` set to the client info.342 For example, the kernel pass-through client (`snd-seq-dummy`) sets343 this flag internally.344 345* The port information gained the new field `direction` to indicate346 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 updated352 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 to354 specific to a certain UMP group.355 356* Each client may set the additional event filter for UMP Groups in357 `group_filter` bitmap. The filter consists of bitmap from 1-based358 Group numbers. For example, when the bit 1 is set, messages from359 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` and364 `SNDRV_SEQ_IOCTL_SET_CLIENT_UMP_INFO`. They are used to get and set365 either `snd_ump_endpoint_info` or `snd_ump_block_info` data366 associated with the sequencer client. The USB MIDI driver provides367 those information from the underlying UMP rawmidi, while a368 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 Block370 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 changed374 dynamically. When the update of Function Block is received from the375 device, ALSA sequencer core changes the corresponding sequencer port376 name and attributes accordingly, and notifies the changes via the377 announcement to the ALSA sequencer system port, similarly like the378 normal port change notification.379 380 381MIDI2 USB Gadget Function Driver382================================383 384The latest kernel contains the support for USB MIDI 2.0 gadget385function driver, which can be used for prototyping and debugging MIDI3862.0 features.387 388`CONFIG_USB_GADGET`, `CONFIG_USB_CONFIGFS` and389`CONFIG_USB_CONFIGFS_F_MIDI2` need to be enabled for the MIDI2 gadget390driver.391 392In addition, for using a gadget driver, you need a working UDC driver.393In the example below, we use `dummy_hcd` driver (enabled via394`CONFIG_USB_DUMMY_HCD`) that is available on PC and VM for debugging395purpose. There are other UDC drivers depending on the platform, and396those can be used for a real device, instead, too.397 398At first, on a system to run the gadget, load `libcomposite` module::399 400 % modprobe libcomposite401 402and you'll have `usb_gadget` subdirectory under configfs space403(typically `/sys/kernel/config` on modern OS). Then create a gadget404instance and add configurations there, for example::405 406 % cd /sys/kernel/config407 % mkdir usb_gadget/g1408 409 % cd usb_gadget/g1410 % mkdir configs/c.1411 % mkdir functions/midi2.usb0412 413 % echo 0x0004 > idProduct414 % echo 0x17b3 > idVendor415 % mkdir strings/0x409416 % echo "ACME Enterprises" > strings/0x409/manufacturer417 % echo "ACMESynth" > strings/0x409/product418 % echo "ABCD12345" > strings/0x409/serialnumber419 420 % mkdir configs/c.1/strings/0x409421 % echo "Monosynth" > configs/c.1/strings/0x409/configuration422 % echo 120 > configs/c.1/MaxPower423 424At this point, there must be a subdirectory `ep.0`, and that is the425configuration for a UMP Endpoint. You can fill the Endpoint426information like::427 428 % echo "ACMESynth" > functions/midi2.usb0/iface_name429 % echo "ACMESynth" > functions/midi2.usb0/ep.0/ep_name430 % echo "ABCD12345" > functions/midi2.usb0/ep.0/product_id431 % echo 0x0123 > functions/midi2.usb0/ep.0/family432 % echo 0x4567 > functions/midi2.usb0/ep.0/model433 % echo 0x123456 > functions/midi2.usb0/ep.0/manufacturer434 % echo 0x12345678 > functions/midi2.usb0/ep.0/sw_revision435 436The default MIDI protocol can be set either 1 or 2::437 438 % echo 2 > functions/midi2.usb0/ep.0/protocol439 440And, you can find a subdirectory `block.0` under this Endpoint441subdirectory. This defines the Function Block information::442 443 % echo "Monosynth" > functions/midi2.usb0/ep.0/block.0/name444 % echo 0 > functions/midi2.usb0/ep.0/block.0/first_group445 % echo 1 > functions/midi2.usb0/ep.0/block.0/num_groups446 447Finally, link the configuration and enable it::448 449 % ln -s functions/midi2.usb0 configs/c.1450 % echo dummy_udc.0 > UDC451 452where `dummy_udc.0` is an example case and it differs depending on the453system. You can find the UDC instances in `/sys/class/udc` and pass454the found name instead::455 456 % ls /sys/class/udc457 dummy_udc.0458 459Now, the MIDI 2.0 gadget device is enabled, and the gadget host460creates a new sound card instance containing a UMP rawmidi device by461`f_midi2` driver::462 463 % cat /proc/asound/cards464 ....465 1 [Gadget ]: f_midi2 - MIDI 2.0 Gadget466 MIDI 2.0 Gadget467 468And on the connected host, a similar card should appear, too, but with469the card and device names given in the configfs above::470 471 % cat /proc/asound/cards472 ....473 2 [ACMESynth ]: USB-Audio - ACMESynth474 ACME Enterprises ACMESynth at usb-dummy_hcd.0-1, high speed475 476You can play a MIDI file on the gadget side::477 478 % aplaymidi -p 20:1 to_host.mid479 480and this will appear as an input from a MIDI device on the connected481host::482 483 % aseqdump -p 20:0 -u 2484 485Vice versa, a playback on the connected host will work as an input on486the gadget, too.487 488Each Function Block may have different direction and UI-hint,489specified via `direction` and `ui_hint` attributes.490Passing `1` is for input-only, `2` for out-only and `3` for491bidirectional (the default value). For example::492 493 % echo 2 > functions/midi2.usb0/ep.0/block.0/direction494 % echo 2 > functions/midi2.usb0/ep.0/block.0/ui_hint495 496When you need more than one Function Blocks, you can create497subdirectories `block.1`, `block.2`, etc dynamically, and configure498them in the configuration procedure above before linking.499For example, to create a second Function Block for a keyboard::500 501 % mkdir functions/midi2.usb0/ep.0/block.1502 % echo "Keyboard" > functions/midi2.usb0/ep.0/block.1/name503 % echo 1 > functions/midi2.usb0/ep.0/block.1/first_group504 % echo 1 > functions/midi2.usb0/ep.0/block.1/num_groups505 % echo 1 > functions/midi2.usb0/ep.0/block.1/direction506 % echo 1 > functions/midi2.usb0/ep.0/block.1/ui_hint507 508The `block.*` subdirectories can be removed dynamically, too (except509for `block.0` which is persistent).510 511For assigning a Function Block for MIDI 1.0 I/O, set up in `is_midi1`512attribute. 1 is for MIDI 1.0, and 2 is for MIDI 1.0 with low speed513connection::514 515 % echo 2 > functions/midi2.usb0/ep.0/block.1/is_midi1516 517For disabling the processing of UMP Stream messages in the gadget518driver, pass `0` to `process_ump` attribute in the top-level config::519 520 % echo 0 > functions/midi2.usb0/process_ump521 522The MIDI 1.0 interface at altset 0 is supported by the gadget driver,523too. When MIDI 1.0 interface is selected by the connected host, the524UMP I/O on the gadget is translated from/to USB MIDI 1.0 packets525accordingly while the gadget driver keeps communicating with the526user-space over UMP rawmidi.527 528MIDI 1.0 ports are set up from the config in each Function Block.529For example::530 531 % echo 0 > functions/midi2.usb0/ep.0/block.0/midi1_first_group532 % echo 1 > functions/midi2.usb0/ep.0/block.0/midi1_num_groups533 534The configuration above will enable the Group 1 (the index 0) for MIDI5351.0 interface. Note that those groups must be in the groups defined536for the Function Block itself.537 538The gadget driver supports more than one UMP Endpoints, too.539Similarly like the Function Blocks, you can create a new subdirectory540`ep.1` (but under the card top-level config) to enable a new Endpoint::541 542 % mkdir functions/midi2.usb0/ep.1543 544and create a new Function Block there. For example, to create 4545Groups for the Function Block of this new Endpoint::546 547 % mkdir functions/midi2.usb0/ep.1/block.0548 % echo 4 > functions/midi2.usb0/ep.1/block.0/num_groups549 550Now, you'll have 4 rawmidi devices in total: the first two are UMP551rawmidi devices for Endpoint 0 and Endpoint 1, and other two for the552legacy MIDI 1.0 rawmidi devices corresponding to both EP 0 and EP 1.553 554The current altsetting on the gadget can be informed via a control555element "Operation Mode" with `RAWMIDI` iface. e.g. you can read it556via `amixer` program running on the gadget host like::557 558 % amixer -c1 cget iface=RAWMIDI,name='Operation Mode'559 ; type=INTEGER,access=r--v----,values=1,min=0,max=2,step=0560 : values=2561 562The value (shown in the second returned line with `: values=`)563indicates 1 for MIDI 1.0 (altset 0), 2 for MIDI 2.0 (altset 1) and 0564for unset.565 566As of now, the configurations can't be changed after binding.567