sound/designs/midi-2.0.rst

12 - Support of Universal MIDI Packet (UMP)
13 - Support of MIDI 2.0 protocol messages
14 - Transparent conversions between UMP and legacy MIDI 1.0 byte stream
15 - MIDI-CI for property and profile configurations
19 aligned, and each message can be put in a single packet.  UMP can send
26 MIDI-CI is a high-level protocol that can talk with the MIDI device
27 for the flexible profiles and configurations.  It's represented in the
31 the encoding/decoding of MIDI protocols on UMP, while MIDI-CI is
32 supported in user-space over the standard SysEx.
39 The access to UMP devices are provided in two ways: the access via
65 When a device supports MIDI 2.0, the USB-audio driver probes and uses
69 `midi2_enable=0` option to snd-usb-audio driver module, too.
77 unexpected UMP command; in such a case, pass `midi2_ump_probe=0`
78 option to snd-usb-audio driver for skipping the UMP v1.1 inquiries.
83 `/dev/snd/midiC*D*` for MIDI 1.0, in order to avoid confusing the
88 show the incoming UMP packets of the card 0 device 0 in the hex
91   % hexdump -C /dev/snd/umpC0D0
98 The 32-bit words in the UMP packet payload are always in CPU native
106 (0-based) UMP Group.  Legacy applications can access to the specified
107 group via each substream in MIDI 1.0 byte stream format.  With the
115 Blocks, where UMP Block is an abstraction introduced in the ALSA UMP
117 Block corresponds to Function Block in UMP 1.1 specification.  When
119 partially from Group Terminal Block (GTB) as defined in USB MIDI 2.0
122 The information of UMP Endpoints and UMP Blocks are found in the proc
139     Groups: 1-1
142   Block 1 (ProtoZOA Ext IN)
145     Groups: 2-2
149 Note that `Groups` field shown in the proc file above indicates the
150 1-based UMP Group numbers (from-to).
157 in the case of USB MIDI, it's taken from `iInterface` of the
165 The protocol capabilities and the actual protocol bits are defined in
172 In addition to the rawmidi interfaces, ALSA sequencer interface
178 and receive in the extended event record for UMP.  The MIDI version is
179 seen in the new `midi_version` field of `snd_seq_client_info`.
181 A UMP packet can be sent/received in a sequencer event embedded by
191 The type of each client can be seen in `/proc/asound/seq/clients`.
199     Port   0 : "Midi Through Port-0" (RWe-)
203       Groups: 1-1
204     UMP Block 1: ProtoZOA Ext IN [Active]
205       Groups: 2-2
207       Groups: 3-3
208     Port   0 : "MIDI 2.0" (RWeX) [In/Out]
209     Port   1 : "ProtoZOA Main" (RWeX) [In/Out]
210     Port   2 : "ProtoZOA Ext IN" (-We-) [Out]
211     Port   3 : "ProtoZOA Ext OUT" (R-e-) [In]
217 In this example, the device has three active groups (Main, Ext IN and
221 the all ports on the device ("catch-all"), while each UMP Group port
229 in the proc outputs.  In the example above, the sequencer ports from 4
233 entry (but with more detailed information) is found in the rawmidi
240 `aseqdump` program on the ProtoZOA Main port in the legacy mode will
243   % aseqdump -p 20:1
250 When you run `aseqdump` in MIDI 2.0 mode, it'll receive the high
253   % aseqdump -u 2 -p 20:1
271   The protocols are specified in two field, the protocol capabilities
274   `SNDRV_UMP_EP_INFO_PROTO_MIDI2`) in the upper byte and the jitter
276   `SNDRV_UMP_EP_INFO_PROTO_JRTS_RX`) in the lower byte.
279   the currently assigned blocks are shown in the Endpoint information.
282   `SNDRV_UMP_IOCTL_BLOCK_INFO`.  The block ID number (0-based) has to
285   (0-based) and the number of groups, the name string of the block,
331   bytes, and the event contains the UMP packet in the payload.
334   indicates the port being UMP-capable.
342   For example, the kernel pass-through client (`snd-seq-dummy`) sets
350   which specifies the associated UMP Group Number (1-based).
351   When it's non-zero, the UMP group field in the UMP packet updated
352   upon delivery to the specified group (corrected to be 0-based).
356 * Each client may set the additional event filter for UMP Groups in
357   `group_filter` bitmap.  The filter consists of bitmap from 1-based
362 * Two new ioctls are added for UMP-capable clients:
368   user-space client may provide its own data via `*_SET` ioctl.
371   Setting the data for a kernel client shall result in an error.
392 In addition, for using a gadget driver, you need a working UDC driver.
393 In the example below, we use `dummy_hcd` driver (enabled via
411   % mkdir functions/midi2.usb0
428   % echo "ACMESynth" > functions/midi2.usb0/iface_name
429   % echo "ACMESynth" > functions/midi2.usb0/ep.0/ep_name
430   % echo "ABCD12345" > functions/midi2.usb0/ep.0/product_id
431   % echo 0x0123 > functions/midi2.usb0/ep.0/family
432   % echo 0x4567 > functions/midi2.usb0/ep.0/model
433   % echo 0x123456 > functions/midi2.usb0/ep.0/manufacturer
434   % echo 0x12345678 > functions/midi2.usb0/ep.0/sw_revision
438   % echo 2 > functions/midi2.usb0/ep.0/protocol
443   % echo "Monosynth" > functions/midi2.usb0/ep.0/block.0/name
444   % echo 0 > functions/midi2.usb0/ep.0/block.0/first_group
445   % echo 1 > functions/midi2.usb0/ep.0/block.0/num_groups
449   % ln -s functions/midi2.usb0 configs/c.1
453 system.  You can find the UDC instances in `/sys/class/udc` and pass
465   1 [Gadget         ]: f_midi2 - MIDI 2.0 Gadget
469 the card and device names given in the configfs above::
473   2 [ACMESynth      ]: USB-Audio - ACMESynth
474                        ACME Enterprises ACMESynth at usb-dummy_hcd.0-1, high speed
478   % aplaymidi -p 20:1 to_host.mid
483   % aseqdump -p 20:0 -u 2
488 Each Function Block may have different direction and UI-hint,
490 Passing `1` is for input-only, `2` for out-only and `3` for
493   % echo 2 > functions/midi2.usb0/ep.0/block.0/direction
494   % echo 2 > functions/midi2.usb0/ep.0/block.0/ui_hint
498 them in the configuration procedure above before linking.
501   % mkdir functions/midi2.usb0/ep.0/block.1
502   % echo "Keyboard" > functions/midi2.usb0/ep.0/block.1/name
503   % echo 1 > functions/midi2.usb0/ep.0/block.1/first_group
504   % echo 1 > functions/midi2.usb0/ep.0/block.1/num_groups
505   % echo 1 > functions/midi2.usb0/ep.0/block.1/direction
506   % echo 1 > functions/midi2.usb0/ep.0/block.1/ui_hint
511 For assigning a Function Block for MIDI 1.0 I/O, set up in `is_midi1`
515   % echo 2 > functions/midi2.usb0/ep.0/block.1/is_midi1
517 For disabling the processing of UMP Stream messages in the gadget
518 driver, pass `0` to `process_ump` attribute in the top-level config::
520   % echo 0 > functions/midi2.usb0/process_ump
526 user-space over UMP rawmidi.
528 MIDI 1.0 ports are set up from the config in each Function Block.
531   % echo 0 > functions/midi2.usb0/ep.0/block.0/midi1_first_group
532   % echo 1 > functions/midi2.usb0/ep.0/block.0/midi1_num_groups
535 1.0 interface.  Note that those groups must be in the groups defined
540 `ep.1` (but under the card top-level config) to enable a new Endpoint::
542   % mkdir functions/midi2.usb0/ep.1
547   % mkdir functions/midi2.usb0/ep.1/block.0
548   % echo 4 > functions/midi2.usb0/ep.1/block.0/num_groups
550 Now, you'll have 4 rawmidi devices in total: the first two are UMP
558   % amixer -c1 cget iface=RAWMIDI,name='Operation Mode'
559   ; type=INTEGER,access=r--v----,values=1,min=0,max=2,step=0
562 The value (shown in the second returned line with `: values=`)