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