16b39e30dSTakashi Iwai================= 26b39e30dSTakashi IwaiMIDI 2.0 on Linux 36b39e30dSTakashi Iwai================= 46b39e30dSTakashi Iwai 56b39e30dSTakashi IwaiGeneral 66b39e30dSTakashi Iwai======= 76b39e30dSTakashi Iwai 86b39e30dSTakashi IwaiMIDI 2.0 is an extended protocol for providing higher resolutions and 96b39e30dSTakashi Iwaimore fine controls over the legacy MIDI 1.0. The fundamental changes 106b39e30dSTakashi Iwaiintroduced for supporting MIDI 2.0 are: 116b39e30dSTakashi Iwai 126b39e30dSTakashi Iwai- Support of Universal MIDI Packet (UMP) 136b39e30dSTakashi Iwai- Support of MIDI 2.0 protocol messages 146b39e30dSTakashi Iwai- Transparent conversions between UMP and legacy MIDI 1.0 byte stream 156b39e30dSTakashi Iwai- MIDI-CI for property and profile configurations 166b39e30dSTakashi Iwai 176b39e30dSTakashi IwaiUMP is a new container format to hold all MIDI protocol 1.0 and MIDI 186b39e30dSTakashi Iwai2.0 protocol messages. Unlike the former byte stream, it's 32bit 196b39e30dSTakashi Iwaialigned, and each message can be put in a single packet. UMP can send 206b39e30dSTakashi Iwaithe events up to 16 "UMP Groups", where each UMP Group contain up to 216b39e30dSTakashi Iwai16 MIDI channels. 226b39e30dSTakashi Iwai 236b39e30dSTakashi IwaiMIDI 2.0 protocol is an extended protocol to achieve the higher 246b39e30dSTakashi Iwairesolution and more controls over the old MIDI 1.0 protocol. 256b39e30dSTakashi Iwai 266b39e30dSTakashi IwaiMIDI-CI is a high-level protocol that can talk with the MIDI device 276b39e30dSTakashi Iwaifor the flexible profiles and configurations. It's represented in the 286b39e30dSTakashi Iwaiform of special SysEx. 296b39e30dSTakashi Iwai 306b39e30dSTakashi IwaiFor Linux implementations, the kernel supports the UMP transport and 316b39e30dSTakashi Iwaithe encoding/decoding of MIDI protocols on UMP, while MIDI-CI is 326b39e30dSTakashi Iwaisupported in user-space over the standard SysEx. 336b39e30dSTakashi Iwai 346b39e30dSTakashi IwaiAs of this writing, only USB MIDI device supports the UMP and Linux 356b39e30dSTakashi Iwai2.0 natively. The UMP support itself is pretty generic, hence it 366b39e30dSTakashi Iwaicould be used by other transport layers, although it could be 376b39e30dSTakashi Iwaiimplemented differently (e.g. as a ALSA sequencer client), too. 386b39e30dSTakashi Iwai 396b39e30dSTakashi IwaiThe access to UMP devices are provided in two ways: the access via 406b39e30dSTakashi Iwairawmidi device and the access via ALSA sequencer API. 416b39e30dSTakashi Iwai 426b39e30dSTakashi IwaiALSA sequencer API was extended to allow the payload of UMP packets. 436b39e30dSTakashi IwaiIt's allowed to connect freely between MIDI 1.0 and MIDI 2.0 sequencer 446b39e30dSTakashi Iwaiclients, and the events are converted transparently. 456b39e30dSTakashi Iwai 466b39e30dSTakashi Iwai 476b39e30dSTakashi IwaiKernel Configuration 486b39e30dSTakashi Iwai==================== 496b39e30dSTakashi Iwai 506b39e30dSTakashi IwaiThe following new configs are added for supporting MIDI 2.0: 516b39e30dSTakashi Iwai`CONFIG_SND_UMP`, `CONFIG_SND_UMP_LEGACY_RAWMIDI`, 526b39e30dSTakashi Iwai`CONFIG_SND_SEQ_UMP`, `CONFIG_SND_SEQ_UMP_CLIENT`, and 536b39e30dSTakashi Iwai`CONFIG_SND_USB_AUDIO_MIDI_V2`. The first visible one is 546b39e30dSTakashi Iwai`CONFIG_SND_USB_AUDIO_MIDI_V2`, and when you choose it (to set `=y`), 556b39e30dSTakashi Iwaithe core support for UMP (`CONFIG_SND_UMP`) and the sequencer binding 566b39e30dSTakashi Iwai(`CONFIG_SND_SEQ_UMP_CLIENT`) will be automatically selected. 576b39e30dSTakashi Iwai 586b39e30dSTakashi IwaiAdditionally, `CONFIG_SND_UMP_LEGACY_RAWMIDI=y` will enable the 596b39e30dSTakashi Iwaisupport for the legacy raw MIDI device for UMP Endpoints. 606b39e30dSTakashi Iwai 616b39e30dSTakashi Iwai 626b39e30dSTakashi IwaiRawmidi Device with USB MIDI 2.0 636b39e30dSTakashi Iwai================================ 646b39e30dSTakashi Iwai 656b39e30dSTakashi IwaiWhen a device supports MIDI 2.0, the USB-audio driver probes and uses 666b39e30dSTakashi Iwaithe MIDI 2.0 interface (that is found always at the altset 1) as 676b39e30dSTakashi Iwaidefault instead of the MIDI 1.0 interface (at altset 0). You can 686b39e30dSTakashi Iwaiswitch back to the binding with the old MIDI 1.0 interface by passing 696b39e30dSTakashi Iwai`midi2_enable=0` option to snd-usb-audio driver module, too. 706b39e30dSTakashi Iwai 71febdfa0eSTakashi IwaiThe USB audio driver tries to query the UMP Endpoint and UMP Function 72febdfa0eSTakashi IwaiBlock information that are provided since UMP v1.1, and builds up the 73febdfa0eSTakashi Iwaitopology based on those information. When the device is older and 74febdfa0eSTakashi Iwaidoesn't respond to the new UMP inquiries, the driver falls back and 75febdfa0eSTakashi Iwaibuilds the topology based on Group Terminal Block (GTB) information 76febdfa0eSTakashi Iwaifrom the USB descriptor. Some device might be screwed up by the 77*60edec9bSTakashi Iwaiunexpected UMP command; in such a case, pass `midi2_ump_probe=0` 78*60edec9bSTakashi Iwaioption to snd-usb-audio driver for skipping the UMP v1.1 inquiries. 79febdfa0eSTakashi Iwai 806b39e30dSTakashi IwaiWhen the MIDI 2.0 device is probed, the kernel creates a rawmidi 816b39e30dSTakashi Iwaidevice for each UMP Endpoint of the device. Its device name is 826b39e30dSTakashi Iwai`/dev/snd/umpC*D*` and different from the standard rawmidi device name 836b39e30dSTakashi Iwai`/dev/snd/midiC*D*` for MIDI 1.0, in order to avoid confusing the 846b39e30dSTakashi Iwailegacy applications accessing mistakenly to UMP devices. 856b39e30dSTakashi Iwai 866b39e30dSTakashi IwaiYou can read and write UMP packet data directly from/to this UMP 876b39e30dSTakashi Iwairawmidi device. For example, reading via `hexdump` like below will 886b39e30dSTakashi Iwaishow the incoming UMP packets of the card 0 device 0 in the hex 896b39e30dSTakashi Iwaiformat:: 906b39e30dSTakashi Iwai 916b39e30dSTakashi Iwai % hexdump -C /dev/snd/umpC0D0 926b39e30dSTakashi Iwai 00000000 01 07 b0 20 00 07 b0 20 64 3c 90 20 64 3c 80 20 |... ... d<. d<. | 936b39e30dSTakashi Iwai 946b39e30dSTakashi IwaiUnlike the MIDI 1.0 byte stream, UMP is a 32bit packet, and the size 956b39e30dSTakashi Iwaifor reading or writing the device is also aligned to 32bit (which is 4 966b39e30dSTakashi Iwaibytes). 976b39e30dSTakashi Iwai 986b39e30dSTakashi IwaiThe 32-bit words in the UMP packet payload are always in CPU native 996b39e30dSTakashi Iwaiendianness. Transport drivers are responsible to convert UMP words 1006b39e30dSTakashi Iwaifrom / to system endianness to required transport endianness / byte 1016b39e30dSTakashi Iwaiorder. 1026b39e30dSTakashi Iwai 1036b39e30dSTakashi IwaiWhen `CONFIG_SND_UMP_LEGACY_RAWMIDI` is set, the driver creates 1046b39e30dSTakashi Iwaianother standard raw MIDI device additionally as `/dev/snd/midiC*D*`. 1056b39e30dSTakashi IwaiThis contains 16 substreams, and each substream corresponds to a 1066b39e30dSTakashi Iwai(0-based) UMP Group. Legacy applications can access to the specified 1076b39e30dSTakashi Iwaigroup via each substream in MIDI 1.0 byte stream format. With the 1086b39e30dSTakashi IwaiALSA rawmidi API, you can open the arbitrary substream, while just 1096b39e30dSTakashi Iwaiopening `/dev/snd/midiC*D*` will end up with opening the first 1106b39e30dSTakashi Iwaisubstream. 1116b39e30dSTakashi Iwai 1126b39e30dSTakashi IwaiEach UMP Endpoint can provide the additional information, constructed 113febdfa0eSTakashi Iwaifrom the information inquired via UMP 1.1 Stream messages or USB MIDI 114febdfa0eSTakashi Iwai2.0 descriptors. And a UMP Endpoint may contain one or more UMP 115febdfa0eSTakashi IwaiBlocks, where UMP Block is an abstraction introduced in the ALSA UMP 116febdfa0eSTakashi Iwaiimplementations to represent the associations among UMP Groups. UMP 117febdfa0eSTakashi IwaiBlock corresponds to Function Block in UMP 1.1 specification. When 118febdfa0eSTakashi IwaiUMP 1.1 Function Block information isn't available, it's filled 119febdfa0eSTakashi Iwaipartially from Group Terminal Block (GTB) as defined in USB MIDI 2.0 120febdfa0eSTakashi Iwaispecifications. 121febdfa0eSTakashi Iwai 1226b39e30dSTakashi IwaiThe information of UMP Endpoints and UMP Blocks are found in the proc 1236b39e30dSTakashi Iwaifile `/proc/asound/card*/midi*`. For example:: 1246b39e30dSTakashi Iwai 1256b39e30dSTakashi Iwai % cat /proc/asound/card1/midi0 1266b39e30dSTakashi Iwai ProtoZOA MIDI 1276b39e30dSTakashi Iwai 1286b39e30dSTakashi Iwai Type: UMP 1296b39e30dSTakashi Iwai EP Name: ProtoZOA 1306b39e30dSTakashi Iwai EP Product ID: ABCD12345678 1316b39e30dSTakashi Iwai UMP Version: 0x0000 1326b39e30dSTakashi Iwai Protocol Caps: 0x00000100 1336b39e30dSTakashi Iwai Protocol: 0x00000100 1346b39e30dSTakashi Iwai Num Blocks: 3 1356b39e30dSTakashi Iwai 1366b39e30dSTakashi Iwai Block 0 (ProtoZOA Main) 1376b39e30dSTakashi Iwai Direction: bidirection 1386b39e30dSTakashi Iwai Active: Yes 1396b39e30dSTakashi Iwai Groups: 1-1 1406b39e30dSTakashi Iwai Is MIDI1: No 1416b39e30dSTakashi Iwai 1426b39e30dSTakashi Iwai Block 1 (ProtoZOA Ext IN) 1436b39e30dSTakashi Iwai Direction: output 1446b39e30dSTakashi Iwai Active: Yes 1456b39e30dSTakashi Iwai Groups: 2-2 1466b39e30dSTakashi Iwai Is MIDI1: Yes (Low Speed) 1476b39e30dSTakashi Iwai .... 1486b39e30dSTakashi Iwai 1496b39e30dSTakashi IwaiNote that `Groups` field shown in the proc file above indicates the 1506b39e30dSTakashi Iwai1-based UMP Group numbers (from-to). 1516b39e30dSTakashi Iwai 1526b39e30dSTakashi IwaiThose additional UMP Endpoint and UMP Block information can be 1536b39e30dSTakashi Iwaiobtained via the new ioctls `SNDRV_UMP_IOCTL_ENDPOINT_INFO` and 1546b39e30dSTakashi Iwai`SNDRV_UMP_IOCTL_BLOCK_INFO`, respectively. 1556b39e30dSTakashi Iwai 1566b39e30dSTakashi IwaiThe rawmidi name and the UMP Endpoint name are usually identical, and 1576b39e30dSTakashi Iwaiin the case of USB MIDI, it's taken from `iInterface` of the 1586b39e30dSTakashi Iwaicorresponding USB MIDI interface descriptor. If it's not provided, 1596b39e30dSTakashi Iwaiit's copied from `iProduct` of the USB device descriptor as a 1606b39e30dSTakashi Iwaifallback. 1616b39e30dSTakashi Iwai 1626b39e30dSTakashi IwaiThe Endpoint Product ID is a string field and supposed to be unique. 1636b39e30dSTakashi IwaiIt's copied from `iSerialNumber` of the device for USB MIDI. 1646b39e30dSTakashi Iwai 1656b39e30dSTakashi IwaiThe protocol capabilities and the actual protocol bits are defined in 1666b39e30dSTakashi Iwai`asound.h`. 1676b39e30dSTakashi Iwai 1686b39e30dSTakashi Iwai 1696b39e30dSTakashi IwaiALSA Sequencer with USB MIDI 2.0 1706b39e30dSTakashi Iwai================================ 1716b39e30dSTakashi Iwai 1726b39e30dSTakashi IwaiIn addition to the rawmidi interfaces, ALSA sequencer interface 1736b39e30dSTakashi Iwaisupports the new UMP MIDI 2.0 device, too. Now, each ALSA sequencer 1746b39e30dSTakashi Iwaiclient may set its MIDI version (0, 1 or 2) to declare itself being 1756b39e30dSTakashi Iwaieither the legacy, UMP MIDI 1.0 or UMP MIDI 2.0 device, respectively. 1766b39e30dSTakashi IwaiThe first, legacy client is the one that sends/receives the old 1776b39e30dSTakashi Iwaisequencer event as was. Meanwhile, UMP MIDI 1.0 and 2.0 clients send 1786b39e30dSTakashi Iwaiand receive in the extended event record for UMP. The MIDI version is 1796b39e30dSTakashi Iwaiseen in the new `midi_version` field of `snd_seq_client_info`. 1806b39e30dSTakashi Iwai 1816b39e30dSTakashi IwaiA UMP packet can be sent/received in a sequencer event embedded by 1826b39e30dSTakashi Iwaispecifying the new event flag bit `SNDRV_SEQ_EVENT_UMP`. When this 1836b39e30dSTakashi Iwaiflag is set, the event has 16 byte (128 bit) data payload for holding 1846b39e30dSTakashi Iwaithe UMP packet. Without the `SNDRV_SEQ_EVENT_UMP` bit flag, the event 1856b39e30dSTakashi Iwaiis treated as a legacy event as it was (with max 12 byte data 1866b39e30dSTakashi Iwaipayload). 1876b39e30dSTakashi Iwai 1886b39e30dSTakashi IwaiWith `SNDRV_SEQ_EVENT_UMP` flag set, the type field of a UMP sequencer 1896b39e30dSTakashi Iwaievent is ignored (but it should be set to 0 as default). 1906b39e30dSTakashi Iwai 1916b39e30dSTakashi IwaiThe type of each client can be seen in `/proc/asound/seq/clients`. 1926b39e30dSTakashi IwaiFor example:: 1936b39e30dSTakashi Iwai 1946b39e30dSTakashi Iwai % cat /proc/asound/seq/clients 1956b39e30dSTakashi Iwai Client info 1966b39e30dSTakashi Iwai cur clients : 3 1976b39e30dSTakashi Iwai .... 1986b39e30dSTakashi Iwai Client 14 : "Midi Through" [Kernel Legacy] 1996b39e30dSTakashi Iwai Port 0 : "Midi Through Port-0" (RWe-) 2006b39e30dSTakashi Iwai Client 20 : "ProtoZOA" [Kernel UMP MIDI1] 2016b39e30dSTakashi Iwai UMP Endpoint: ProtoZOA 2026b39e30dSTakashi Iwai UMP Block 0: ProtoZOA Main [Active] 2036b39e30dSTakashi Iwai Groups: 1-1 2046b39e30dSTakashi Iwai UMP Block 1: ProtoZOA Ext IN [Active] 2056b39e30dSTakashi Iwai Groups: 2-2 2066b39e30dSTakashi Iwai UMP Block 2: ProtoZOA Ext OUT [Active] 2076b39e30dSTakashi Iwai Groups: 3-3 2086b39e30dSTakashi Iwai Port 0 : "MIDI 2.0" (RWeX) [In/Out] 2096b39e30dSTakashi Iwai Port 1 : "ProtoZOA Main" (RWeX) [In/Out] 2106b39e30dSTakashi Iwai Port 2 : "ProtoZOA Ext IN" (-We-) [Out] 2116b39e30dSTakashi Iwai Port 3 : "ProtoZOA Ext OUT" (R-e-) [In] 2126b39e30dSTakashi Iwai 2136b39e30dSTakashi IwaiHere you can find two types of kernel clients, "Legacy" for client 14, 2146b39e30dSTakashi Iwaiand "UMP MIDI1" for client 20, which is a USB MIDI 2.0 device. 2156b39e30dSTakashi IwaiA USB MIDI 2.0 client gives always the port 0 as "MIDI 2.0" and the 2166b39e30dSTakashi Iwairest ports from 1 for each UMP Group (e.g. port 1 for Group 1). 2176b39e30dSTakashi IwaiIn this example, the device has three active groups (Main, Ext IN and 2186b39e30dSTakashi IwaiExt OUT), and those are exposed as sequencer ports from 1 to 3. 2196b39e30dSTakashi IwaiThe "MIDI 2.0" port is for a UMP Endpoint, and its difference from 2206b39e30dSTakashi Iwaiother UMP Group ports is that UMP Endpoint port sends the events from 2216b39e30dSTakashi Iwaithe all ports on the device ("catch-all"), while each UMP Group port 2226b39e30dSTakashi Iwaisends only the events from the given UMP Group. 223febdfa0eSTakashi IwaiAlso, UMP groupless messages (such as the UMP message type 0x0f) are 224febdfa0eSTakashi Iwaisent only to the UMP Endpoint port. 2256b39e30dSTakashi Iwai 2266b39e30dSTakashi IwaiNote that, although each UMP sequencer client usually creates 16 2276b39e30dSTakashi Iwaiports, those ports that don't belong to any UMP Blocks (or belonging 2286b39e30dSTakashi Iwaito inactive UMP Blocks) are marked as inactive, and they don't appear 2296b39e30dSTakashi Iwaiin the proc outputs. In the example above, the sequencer ports from 4 2306b39e30dSTakashi Iwaito 16 are present but not shown there. 2316b39e30dSTakashi Iwai 2326b39e30dSTakashi IwaiThe proc file above shows the UMP Block information, too. The same 2336b39e30dSTakashi Iwaientry (but with more detailed information) is found in the rawmidi 2346b39e30dSTakashi Iwaiproc output. 2356b39e30dSTakashi Iwai 2366b39e30dSTakashi IwaiWhen clients are connected between different MIDI versions, the events 2376b39e30dSTakashi Iwaiare translated automatically depending on the client's version, not 2386b39e30dSTakashi Iwaionly between the legacy and the UMP MIDI 1.0/2.0 types, but also 2396b39e30dSTakashi Iwaibetween UMP MIDI 1.0 and 2.0 types, too. For example, running 2406b39e30dSTakashi Iwai`aseqdump` program on the ProtoZOA Main port in the legacy mode will 2416b39e30dSTakashi Iwaigive you the output like:: 2426b39e30dSTakashi Iwai 2436b39e30dSTakashi Iwai % aseqdump -p 20:1 2446b39e30dSTakashi Iwai Waiting for data. Press Ctrl+C to end. 2456b39e30dSTakashi Iwai Source Event Ch Data 2466b39e30dSTakashi Iwai 20:1 Note on 0, note 60, velocity 100 2476b39e30dSTakashi Iwai 20:1 Note off 0, note 60, velocity 100 2486b39e30dSTakashi Iwai 20:1 Control change 0, controller 11, value 4 2496b39e30dSTakashi Iwai 2506b39e30dSTakashi IwaiWhen you run `aseqdump` in MIDI 2.0 mode, it'll receive the high 2516b39e30dSTakashi Iwaiprecision data like:: 2526b39e30dSTakashi Iwai 2536b39e30dSTakashi Iwai % aseqdump -u 2 -p 20:1 2546b39e30dSTakashi Iwai Waiting for data. Press Ctrl+C to end. 2556b39e30dSTakashi Iwai Source Event Ch Data 2566b39e30dSTakashi Iwai 20:1 Note on 0, note 60, velocity 0xc924, attr type = 0, data = 0x0 2576b39e30dSTakashi Iwai 20:1 Note off 0, note 60, velocity 0xc924, attr type = 0, data = 0x0 2586b39e30dSTakashi Iwai 20:1 Control change 0, controller 11, value 0x2000000 2596b39e30dSTakashi Iwai 2606b39e30dSTakashi Iwaiwhile the data is automatically converted by ALSA sequencer core. 2616b39e30dSTakashi Iwai 2626b39e30dSTakashi Iwai 2636b39e30dSTakashi IwaiRawmidi API Extensions 2646b39e30dSTakashi Iwai====================== 2656b39e30dSTakashi Iwai 2666b39e30dSTakashi Iwai* The additional UMP Endpoint information can be obtained via the new 2676b39e30dSTakashi Iwai ioctl `SNDRV_UMP_IOCTL_ENDPOINT_INFO`. It contains the associated 2686b39e30dSTakashi Iwai card and device numbers, the bit flags, the protocols, the number of 2696b39e30dSTakashi Iwai UMP Blocks, the name string of the endpoint, etc. 2706b39e30dSTakashi Iwai 2716b39e30dSTakashi Iwai The protocols are specified in two field, the protocol capabilities 2726b39e30dSTakashi Iwai and the current protocol. Both contain the bit flags specifying the 2736b39e30dSTakashi Iwai MIDI protocol version (`SNDRV_UMP_EP_INFO_PROTO_MIDI1` or 2746b39e30dSTakashi Iwai `SNDRV_UMP_EP_INFO_PROTO_MIDI2`) in the upper byte and the jitter 2756b39e30dSTakashi Iwai reduction timestamp (`SNDRV_UMP_EP_INFO_PROTO_JRTS_TX` and 2766b39e30dSTakashi Iwai `SNDRV_UMP_EP_INFO_PROTO_JRTS_RX`) in the lower byte. 2776b39e30dSTakashi Iwai 2786b39e30dSTakashi Iwai A UMP Endpoint may contain up to 32 UMP Blocks, and the number of 2796b39e30dSTakashi Iwai the currently assigned blocks are shown in the Endpoint information. 2806b39e30dSTakashi Iwai 2816b39e30dSTakashi Iwai* Each UMP Block information can be obtained via another new ioctl 2826b39e30dSTakashi Iwai `SNDRV_UMP_IOCTL_BLOCK_INFO`. The block ID number (0-based) has to 2836b39e30dSTakashi Iwai be passed for the block to query. The received data contains the 2846b39e30dSTakashi Iwai associated the direction of the block, the first associated group ID 2856b39e30dSTakashi Iwai (0-based) and the number of groups, the name string of the block, 2866b39e30dSTakashi Iwai etc. 2876b39e30dSTakashi Iwai 2886b39e30dSTakashi Iwai The direction is either `SNDRV_UMP_DIR_INPUT`, 2896b39e30dSTakashi Iwai `SNDRV_UMP_DIR_OUTPUT` or `SNDRV_UMP_DIR_BIDIRECTION`. 2906b39e30dSTakashi Iwai 291febdfa0eSTakashi Iwai* For the device supports UMP v1.1, the UMP MIDI protocol can be 292febdfa0eSTakashi Iwai switched via "Stream Configuration Request" message (UMP type 0x0f, 293febdfa0eSTakashi Iwai status 0x05). When UMP core receives such a message, it updates the 294febdfa0eSTakashi Iwai UMP EP info and the corresponding sequencer clients as well. 295febdfa0eSTakashi Iwai 2966b39e30dSTakashi Iwai 2976b39e30dSTakashi IwaiControl API Extensions 2986b39e30dSTakashi Iwai====================== 2996b39e30dSTakashi Iwai 3006b39e30dSTakashi Iwai* The new ioctl `SNDRV_CTL_IOCTL_UMP_NEXT_DEVICE` is introduced for 3016b39e30dSTakashi Iwai querying the next UMP rawmidi device, while the existing ioctl 3026b39e30dSTakashi Iwai `SNDRV_CTL_IOCTL_RAWMIDI_NEXT_DEVICE` queries only the legacy 3036b39e30dSTakashi Iwai rawmidi devices. 3046b39e30dSTakashi Iwai 3056b39e30dSTakashi Iwai For setting the subdevice (substream number) to be opened, use the 3066b39e30dSTakashi Iwai ioctl `SNDRV_CTL_IOCTL_RAWMIDI_PREFER_SUBDEVICE` like the normal 3076b39e30dSTakashi Iwai rawmidi. 3086b39e30dSTakashi Iwai 3096b39e30dSTakashi Iwai* Two new ioctls `SNDRV_CTL_IOCTL_UMP_ENDPOINT_INFO` and 3106b39e30dSTakashi Iwai `SNDRV_CTL_IOCTL_UMP_BLOCK_INFO` provide the UMP Endpoint and UMP 3116b39e30dSTakashi Iwai Block information of the specified UMP device via ALSA control API 3126b39e30dSTakashi Iwai without opening the actual (UMP) rawmidi device. 3136b39e30dSTakashi Iwai The `card` field is ignored upon inquiry, always tied with the card 3146b39e30dSTakashi Iwai of the control interface. 3156b39e30dSTakashi Iwai 3166b39e30dSTakashi Iwai 3176b39e30dSTakashi IwaiSequencer API Extensions 3186b39e30dSTakashi Iwai======================== 3196b39e30dSTakashi Iwai 3206b39e30dSTakashi Iwai* `midi_version` field is added to `snd_seq_client_info` to indicate 3216b39e30dSTakashi Iwai the current MIDI version (either 0, 1 or 2) of each client. 3226b39e30dSTakashi Iwai When `midi_version` is 1 or 2, the alignment of read from a UMP 3236b39e30dSTakashi Iwai sequencer client is also changed from the former 28 bytes to 32 3246b39e30dSTakashi Iwai bytes for the extended payload. The alignment size for the write 3256b39e30dSTakashi Iwai isn't changed, but each event size may differ depending on the new 3266b39e30dSTakashi Iwai bit flag below. 3276b39e30dSTakashi Iwai 3286b39e30dSTakashi Iwai* `SNDRV_SEQ_EVENT_UMP` flag bit is added for each sequencer event 3296b39e30dSTakashi Iwai flags. When this bit flag is set, the sequencer event is extended 3306b39e30dSTakashi Iwai to have a larger payload of 16 bytes instead of the legacy 12 3316b39e30dSTakashi Iwai bytes, and the event contains the UMP packet in the payload. 3326b39e30dSTakashi Iwai 3336b39e30dSTakashi Iwai* The new sequencer port type bit (`SNDRV_SEQ_PORT_TYPE_MIDI_UMP`) 3346b39e30dSTakashi Iwai indicates the port being UMP-capable. 3356b39e30dSTakashi Iwai 3366b39e30dSTakashi Iwai* The sequencer ports have new capability bits to indicate the 3376b39e30dSTakashi Iwai inactive ports (`SNDRV_SEQ_PORT_CAP_INACTIVE`) and the UMP Endpoint 3386b39e30dSTakashi Iwai port (`SNDRV_SEQ_PORT_CAP_UMP_ENDPOINT`). 3396b39e30dSTakashi Iwai 3406b39e30dSTakashi Iwai* The event conversion of ALSA sequencer clients can be suppressed the 3416b39e30dSTakashi Iwai new filter bit `SNDRV_SEQ_FILTER_NO_CONVERT` set to the client info. 3426b39e30dSTakashi Iwai For example, the kernel pass-through client (`snd-seq-dummy`) sets 3436b39e30dSTakashi Iwai this flag internally. 3446b39e30dSTakashi Iwai 3456b39e30dSTakashi Iwai* The port information gained the new field `direction` to indicate 3466b39e30dSTakashi Iwai the direction of the port (either `SNDRV_SEQ_PORT_DIR_INPUT`, 3476b39e30dSTakashi Iwai `SNDRV_SEQ_PORT_DIR_OUTPUT` or `SNDRV_SEQ_PORT_DIR_BIDIRECTION`). 3486b39e30dSTakashi Iwai 3496b39e30dSTakashi Iwai* Another additional field for the port information is `ump_group` 3506b39e30dSTakashi Iwai which specifies the associated UMP Group Number (1-based). 3516b39e30dSTakashi Iwai When it's non-zero, the UMP group field in the UMP packet updated 3526b39e30dSTakashi Iwai upon delivery to the specified group (corrected to be 0-based). 3536b39e30dSTakashi Iwai Each sequencer port is supposed to set this field if it's a port to 3546b39e30dSTakashi Iwai specific to a certain UMP group. 3556b39e30dSTakashi Iwai 3566b39e30dSTakashi Iwai* Each client may set the additional event filter for UMP Groups in 3576b39e30dSTakashi Iwai `group_filter` bitmap. The filter consists of bitmap from 1-based 3586b39e30dSTakashi Iwai Group numbers. For example, when the bit 1 is set, messages from 3596b39e30dSTakashi Iwai Group 1 (i.e. the very first group) are filtered and not delivered. 360febdfa0eSTakashi Iwai The bit 0 is used for filtering UMP groupless messages. 3616b39e30dSTakashi Iwai 3626b39e30dSTakashi Iwai* Two new ioctls are added for UMP-capable clients: 3636b39e30dSTakashi Iwai `SNDRV_SEQ_IOCTL_GET_CLIENT_UMP_INFO` and 3646b39e30dSTakashi Iwai `SNDRV_SEQ_IOCTL_SET_CLIENT_UMP_INFO`. They are used to get and set 3656b39e30dSTakashi Iwai either `snd_ump_endpoint_info` or `snd_ump_block_info` data 3666b39e30dSTakashi Iwai associated with the sequencer client. The USB MIDI driver provides 3676b39e30dSTakashi Iwai those information from the underlying UMP rawmidi, while a 3686b39e30dSTakashi Iwai user-space client may provide its own data via `*_SET` ioctl. 3696b39e30dSTakashi Iwai For an Endpoint data, pass 0 to the `type` field, while for a Block 3706b39e30dSTakashi Iwai data, pass the block number + 1 to the `type` field. 3716b39e30dSTakashi Iwai Setting the data for a kernel client shall result in an error. 372febdfa0eSTakashi Iwai 373febdfa0eSTakashi Iwai* With UMP 1.1, Function Block information may be changed 374febdfa0eSTakashi Iwai dynamically. When the update of Function Block is received from the 375febdfa0eSTakashi Iwai device, ALSA sequencer core changes the corresponding sequencer port 376febdfa0eSTakashi Iwai name and attributes accordingly, and notifies the changes via the 377febdfa0eSTakashi Iwai announcement to the ALSA sequencer system port, similarly like the 378febdfa0eSTakashi Iwai normal port change notification. 379e240cff9STakashi Iwai 380e240cff9STakashi Iwai 381e240cff9STakashi IwaiMIDI2 USB Gadget Function Driver 382e240cff9STakashi Iwai================================ 383e240cff9STakashi Iwai 384e240cff9STakashi IwaiThe latest kernel contains the support for USB MIDI 2.0 gadget 385e240cff9STakashi Iwaifunction driver, which can be used for prototyping and debugging MIDI 386e240cff9STakashi Iwai2.0 features. 387e240cff9STakashi Iwai 388e240cff9STakashi Iwai`CONFIG_USB_GADGET`, `CONFIG_USB_CONFIGFS` and 389e240cff9STakashi Iwai`CONFIG_USB_CONFIGFS_F_MIDI2` need to be enabled for the MIDI2 gadget 390e240cff9STakashi Iwaidriver. 391e240cff9STakashi Iwai 392e240cff9STakashi IwaiIn addition, for using a gadget driver, you need a working UDC driver. 393e240cff9STakashi IwaiIn the example below, we use `dummy_hcd` driver (enabled via 394e240cff9STakashi Iwai`CONFIG_USB_DUMMY_HCD`) that is available on PC and VM for debugging 395e240cff9STakashi Iwaipurpose. There are other UDC drivers depending on the platform, and 396e240cff9STakashi Iwaithose can be used for a real device, instead, too. 397e240cff9STakashi Iwai 398e240cff9STakashi IwaiAt first, on a system to run the gadget, load `libcomposite` module:: 399e240cff9STakashi Iwai 400e240cff9STakashi Iwai % modprobe libcomposite 401e240cff9STakashi Iwai 402e240cff9STakashi Iwaiand you'll have `usb_gadget` subdirectory under configfs space 403e240cff9STakashi Iwai(typically `/sys/kernel/config` on modern OS). Then create a gadget 404e240cff9STakashi Iwaiinstance and add configurations there, for example:: 405e240cff9STakashi Iwai 406e240cff9STakashi Iwai % cd /sys/kernel/config 407e240cff9STakashi Iwai % mkdir usb_gadget/g1 408e240cff9STakashi Iwai 409e240cff9STakashi Iwai % cd usb_gadget/g1 410e240cff9STakashi Iwai % mkdir configs/c.1 411e240cff9STakashi Iwai % mkdir functions/midi2.usb0 412e240cff9STakashi Iwai 413e240cff9STakashi Iwai % echo 0x0004 > idProduct 414e240cff9STakashi Iwai % echo 0x17b3 > idVendor 415e240cff9STakashi Iwai % mkdir strings/0x409 416e240cff9STakashi Iwai % echo "ACME Enterprises" > strings/0x409/manufacturer 417e240cff9STakashi Iwai % echo "ACMESynth" > strings/0x409/product 418e240cff9STakashi Iwai % echo "ABCD12345" > strings/0x409/serialnumber 419e240cff9STakashi Iwai 420e240cff9STakashi Iwai % mkdir configs/c.1/strings/0x409 421e240cff9STakashi Iwai % echo "Monosynth" > configs/c.1/strings/0x409/configuration 422e240cff9STakashi Iwai % echo 120 > configs/c.1/MaxPower 423e240cff9STakashi Iwai 424e240cff9STakashi IwaiAt this point, there must be a subdirectory `ep.0`, and that is the 425e240cff9STakashi Iwaiconfiguration for a UMP Endpoint. You can fill the Endpoint 426e240cff9STakashi Iwaiinformation like:: 427e240cff9STakashi Iwai 428e240cff9STakashi Iwai % echo "ACMESynth" > functions/midi2.usb0/iface_name 429e240cff9STakashi Iwai % echo "ACMESynth" > functions/midi2.usb0/ep.0/ep_name 430e240cff9STakashi Iwai % echo "ABCD12345" > functions/midi2.usb0/ep.0/product_id 431e240cff9STakashi Iwai % echo 0x0123 > functions/midi2.usb0/ep.0/family 432e240cff9STakashi Iwai % echo 0x4567 > functions/midi2.usb0/ep.0/model 433e240cff9STakashi Iwai % echo 0x123456 > functions/midi2.usb0/ep.0/manufacturer 434e240cff9STakashi Iwai % echo 0x12345678 > functions/midi2.usb0/ep.0/sw_revision 435e240cff9STakashi Iwai 436e240cff9STakashi IwaiThe default MIDI protocol can be set either 1 or 2:: 437e240cff9STakashi Iwai 438e240cff9STakashi Iwai % echo 2 > functions/midi2.usb0/ep.0/protocol 439e240cff9STakashi Iwai 440e240cff9STakashi IwaiAnd, you can find a subdirectory `block.0` under this Endpoint 441e240cff9STakashi Iwaisubdirectory. This defines the Function Block information:: 442e240cff9STakashi Iwai 443e240cff9STakashi Iwai % echo "Monosynth" > functions/midi2.usb0/ep.0/block.0/name 444e240cff9STakashi Iwai % echo 0 > functions/midi2.usb0/ep.0/block.0/first_group 445e240cff9STakashi Iwai % echo 1 > functions/midi2.usb0/ep.0/block.0/num_groups 446e240cff9STakashi Iwai 447e240cff9STakashi IwaiFinally, link the configuration and enable it:: 448e240cff9STakashi Iwai 449e240cff9STakashi Iwai % ln -s functions/midi2.usb0 configs/c.1 450e240cff9STakashi Iwai % echo dummy_udc.0 > UDC 451e240cff9STakashi Iwai 452e240cff9STakashi Iwaiwhere `dummy_udc.0` is an example case and it differs depending on the 453e240cff9STakashi Iwaisystem. You can find the UDC instances in `/sys/class/udc` and pass 454e240cff9STakashi Iwaithe found name instead:: 455e240cff9STakashi Iwai 456e240cff9STakashi Iwai % ls /sys/class/udc 457e240cff9STakashi Iwai dummy_udc.0 458e240cff9STakashi Iwai 459e240cff9STakashi IwaiNow, the MIDI 2.0 gadget device is enabled, and the gadget host 460e240cff9STakashi Iwaicreates a new sound card instance containing a UMP rawmidi device by 461e240cff9STakashi Iwai`f_midi2` driver:: 462e240cff9STakashi Iwai 463e240cff9STakashi Iwai % cat /proc/asound/cards 464e240cff9STakashi Iwai .... 465e240cff9STakashi Iwai 1 [Gadget ]: f_midi2 - MIDI 2.0 Gadget 466e240cff9STakashi Iwai MIDI 2.0 Gadget 467e240cff9STakashi Iwai 468e240cff9STakashi IwaiAnd on the connected host, a similar card should appear, too, but with 469e240cff9STakashi Iwaithe card and device names given in the configfs above:: 470e240cff9STakashi Iwai 471e240cff9STakashi Iwai % cat /proc/asound/cards 472e240cff9STakashi Iwai .... 473e240cff9STakashi Iwai 2 [ACMESynth ]: USB-Audio - ACMESynth 474e240cff9STakashi Iwai ACME Enterprises ACMESynth at usb-dummy_hcd.0-1, high speed 475e240cff9STakashi Iwai 476e240cff9STakashi IwaiYou can play a MIDI file on the gadget side:: 477e240cff9STakashi Iwai 478e240cff9STakashi Iwai % aplaymidi -p 20:1 to_host.mid 479e240cff9STakashi Iwai 480e240cff9STakashi Iwaiand this will appear as an input from a MIDI device on the connected 481e240cff9STakashi Iwaihost:: 482e240cff9STakashi Iwai 483e240cff9STakashi Iwai % aseqdump -p 20:0 -u 2 484e240cff9STakashi Iwai 485e240cff9STakashi IwaiVice versa, a playback on the connected host will work as an input on 486e240cff9STakashi Iwaithe gadget, too. 487e240cff9STakashi Iwai 488e240cff9STakashi IwaiEach Function Block may have different direction and UI-hint, 489e240cff9STakashi Iwaispecified via `direction` and `ui_hint` attributes. 490e240cff9STakashi IwaiPassing `1` is for input-only, `2` for out-only and `3` for 491e240cff9STakashi Iwaibidirectional (the default value). For example:: 492e240cff9STakashi Iwai 493e240cff9STakashi Iwai % echo 2 > functions/midi2.usb0/ep.0/block.0/direction 494e240cff9STakashi Iwai % echo 2 > functions/midi2.usb0/ep.0/block.0/ui_hint 495e240cff9STakashi Iwai 496e240cff9STakashi IwaiWhen you need more than one Function Blocks, you can create 497e240cff9STakashi Iwaisubdirectories `block.1`, `block.2`, etc dynamically, and configure 498e240cff9STakashi Iwaithem in the configuration procedure above before linking. 499e240cff9STakashi IwaiFor example, to create a second Function Block for a keyboard:: 500e240cff9STakashi Iwai 501e240cff9STakashi Iwai % mkdir functions/midi2.usb0/ep.0/block.1 502e240cff9STakashi Iwai % echo "Keyboard" > functions/midi2.usb0/ep.0/block.1/name 503e240cff9STakashi Iwai % echo 1 > functions/midi2.usb0/ep.0/block.1/first_group 504e240cff9STakashi Iwai % echo 1 > functions/midi2.usb0/ep.0/block.1/num_groups 505e240cff9STakashi Iwai % echo 1 > functions/midi2.usb0/ep.0/block.1/direction 506e240cff9STakashi Iwai % echo 1 > functions/midi2.usb0/ep.0/block.1/ui_hint 507e240cff9STakashi Iwai 508e240cff9STakashi IwaiThe `block.*` subdirectories can be removed dynamically, too (except 509e240cff9STakashi Iwaifor `block.0` which is persistent). 510e240cff9STakashi Iwai 511e240cff9STakashi IwaiFor assigning a Function Block for MIDI 1.0 I/O, set up in `is_midi1` 512e240cff9STakashi Iwaiattribute. 1 is for MIDI 1.0, and 2 is for MIDI 1.0 with low speed 513e240cff9STakashi Iwaiconnection:: 514e240cff9STakashi Iwai 515e240cff9STakashi Iwai % echo 2 > functions/midi2.usb0/ep.0/block.1/is_midi1 516e240cff9STakashi Iwai 517e240cff9STakashi IwaiFor disabling the processing of UMP Stream messages in the gadget 518a3ca016aSTakashi Iwaidriver, pass `0` to `process_ump` attribute in the top-level config:: 519e240cff9STakashi Iwai 520e240cff9STakashi Iwai % echo 0 > functions/midi2.usb0/process_ump 521e240cff9STakashi Iwai 522e240cff9STakashi IwaiThe MIDI 1.0 interface at altset 0 is supported by the gadget driver, 523e240cff9STakashi Iwaitoo. When MIDI 1.0 interface is selected by the connected host, the 524e240cff9STakashi IwaiUMP I/O on the gadget is translated from/to USB MIDI 1.0 packets 525e240cff9STakashi Iwaiaccordingly while the gadget driver keeps communicating with the 526e240cff9STakashi Iwaiuser-space over UMP rawmidi. 527e240cff9STakashi Iwai 528e240cff9STakashi IwaiMIDI 1.0 ports are set up from the config in each Function Block. 529e240cff9STakashi IwaiFor example:: 530e240cff9STakashi Iwai 531e240cff9STakashi Iwai % echo 0 > functions/midi2.usb0/ep.0/block.0/midi1_first_group 532e240cff9STakashi Iwai % echo 1 > functions/midi2.usb0/ep.0/block.0/midi1_num_groups 533e240cff9STakashi Iwai 534e240cff9STakashi IwaiThe configuration above will enable the Group 1 (the index 0) for MIDI 535e240cff9STakashi Iwai1.0 interface. Note that those groups must be in the groups defined 536e240cff9STakashi Iwaifor the Function Block itself. 537e240cff9STakashi Iwai 538e240cff9STakashi IwaiThe gadget driver supports more than one UMP Endpoints, too. 539e240cff9STakashi IwaiSimilarly like the Function Blocks, you can create a new subdirectory 540e240cff9STakashi Iwai`ep.1` (but under the card top-level config) to enable a new Endpoint:: 541e240cff9STakashi Iwai 542e240cff9STakashi Iwai % mkdir functions/midi2.usb0/ep.1 543e240cff9STakashi Iwai 544e240cff9STakashi Iwaiand create a new Function Block there. For example, to create 4 545e240cff9STakashi IwaiGroups for the Function Block of this new Endpoint:: 546e240cff9STakashi Iwai 547e240cff9STakashi Iwai % mkdir functions/midi2.usb0/ep.1/block.0 548e240cff9STakashi Iwai % echo 4 > functions/midi2.usb0/ep.1/block.0/num_groups 549e240cff9STakashi Iwai 550e240cff9STakashi IwaiNow, you'll have 4 rawmidi devices in total: the first two are UMP 551e240cff9STakashi Iwairawmidi devices for Endpoint 0 and Endpoint 1, and other two for the 552e240cff9STakashi Iwailegacy MIDI 1.0 rawmidi devices corresponding to both EP 0 and EP 1. 553e240cff9STakashi Iwai 554e240cff9STakashi IwaiThe current altsetting on the gadget can be informed via a control 555e240cff9STakashi Iwaielement "Operation Mode" with `RAWMIDI` iface. e.g. you can read it 556e240cff9STakashi Iwaivia `amixer` program running on the gadget host like:: 557e240cff9STakashi Iwai 558e240cff9STakashi Iwai % amixer -c1 cget iface=RAWMIDI,name='Operation Mode' 559e240cff9STakashi Iwai ; type=INTEGER,access=r--v----,values=1,min=0,max=2,step=0 560e240cff9STakashi Iwai : values=2 561e240cff9STakashi Iwai 562e240cff9STakashi IwaiThe value (shown in the second returned line with `: values=`) 563e240cff9STakashi Iwaiindicates 1 for MIDI 1.0 (altset 0), 2 for MIDI 2.0 (altset 1) and 0 564e240cff9STakashi Iwaifor unset. 565e240cff9STakashi Iwai 566e240cff9STakashi IwaiAs of now, the configurations can't be changed after binding. 567