sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget*/translations/zh_CN/sound/designs/midi-2.0modnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget*/translations/zh_TW/sound/designs/midi-2.0modnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget*/translations/it_IT/sound/designs/midi-2.0modnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget*/translations/ja_JP/sound/designs/midi-2.0modnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget*/translations/ko_KR/sound/designs/midi-2.0modnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget*/translations/sp_SP/sound/designs/midi-2.0modnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhsection)}(hhh](htitle)}(hMIDI 2.0 on Linuxh]hMIDI 2.0 on Linux}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhD/var/lib/git/docbuild/linux/Documentation/sound/designs/midi-2.0.rsthKubh)}(hhh](h)}(hGeneralh]hGeneral}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hMIDI 2.0 is an extended protocol for providing higher resolutions and more fine controls over the legacy MIDI 1.0. The fundamental changes introduced for supporting MIDI 2.0 are:h]hMIDI 2.0 is an extended protocol for providing higher resolutions and more fine controls over the legacy MIDI 1.0. The fundamental changes introduced for supporting MIDI 2.0 are:}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh bullet_list)}(hhh](h list_item)}(h&Support of Universal MIDI Packet (UMP)h]h)}(hhh]h&Support of Universal MIDI Packet (UMP)}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhubah}(h]h ]h"]h$]h&]uh1hhhhhhhhNubh)}(h%Support of MIDI 2.0 protocol messagesh]h)}(hhh]h%Support of MIDI 2.0 protocol messages}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhubah}(h]h ]h"]h$]h&]uh1hhhhhhhhNubh)}(hCTransparent conversions between UMP and legacy MIDI 1.0 byte streamh]h)}(hjh]hCTransparent conversions between UMP and legacy MIDI 1.0 byte stream}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1hhhhhhhhNubh)}(h0MIDI-CI for property and profile configurations h]h)}(h/MIDI-CI for property and profile configurationsh]h/MIDI-CI for property and profile configurations}(hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj$ubah}(h]h ]h"]h$]h&]uh1hhhhhhhhNubeh}(h]h ]h"]h$]h&]bullet-uh1hhhhK hhhhubh)}(hX$UMP is a new container format to hold all MIDI protocol 1.0 and MIDI 2.0 protocol messages. Unlike the former byte stream, it's 32bit aligned, and each message can be put in a single packet. UMP can send the events up to 16 "UMP Groups", where each UMP Group contain up to 16 MIDI channels.h]hX*UMP is a new container format to hold all MIDI protocol 1.0 and MIDI 2.0 protocol messages. Unlike the former byte stream, it’s 32bit aligned, and each message can be put in a single packet. UMP can send the events up to 16 “UMP Groups”, where each UMP Group contain up to 16 MIDI channels.}(hjDhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(h|MIDI 2.0 protocol is an extended protocol to achieve the higher resolution and more controls over the old MIDI 1.0 protocol.h]h|MIDI 2.0 protocol is an extended protocol to achieve the higher resolution and more controls over the old MIDI 1.0 protocol.}(hjRhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hMIDI-CI is a high-level protocol that can talk with the MIDI device for the flexible profiles and configurations. It's represented in the form of special SysEx.h]hMIDI-CI is a high-level protocol that can talk with the MIDI device for the flexible profiles and configurations. It’s represented in the form of special SysEx.}(hj`hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hFor Linux implementations, the kernel supports the UMP transport and the encoding/decoding of MIDI protocols on UMP, while MIDI-CI is supported in user-space over the standard SysEx.h]hFor Linux implementations, the kernel supports the UMP transport and the encoding/decoding of MIDI protocols on UMP, while MIDI-CI is supported in user-space over the standard SysEx.}(hjnhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hXAs of this writing, only USB MIDI device supports the UMP and Linux 2.0 natively. The UMP support itself is pretty generic, hence it could be used by other transport layers, although it could be implemented differently (e.g. as a ALSA sequencer client), too.h]hXAs of this writing, only USB MIDI device supports the UMP and Linux 2.0 natively. The UMP support itself is pretty generic, hence it could be used by other transport layers, although it could be implemented differently (e.g. as a ALSA sequencer client), too.}(hj|hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK"hhhhubh)}(hxThe access to UMP devices are provided in two ways: the access via rawmidi device and the access via ALSA sequencer API.h]hxThe access to UMP devices are provided in two ways: the access via rawmidi device and the access via ALSA sequencer API.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK'hhhhubh)}(hALSA sequencer API was extended to allow the payload of UMP packets. It's allowed to connect freely between MIDI 1.0 and MIDI 2.0 sequencer clients, and the events are converted transparently.h]hALSA sequencer API was extended to allow the payload of UMP packets. It’s allowed to connect freely between MIDI 1.0 and MIDI 2.0 sequencer clients, and the events are converted transparently.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK*hhhhubeh}(h]generalah ]h"]generalah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hKernel Configurationh]hKernel Configuration}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK0ubh)}(hXThe following new configs are added for supporting MIDI 2.0: `CONFIG_SND_UMP`, `CONFIG_SND_UMP_LEGACY_RAWMIDI`, `CONFIG_SND_SEQ_UMP`, `CONFIG_SND_SEQ_UMP_CLIENT`, and `CONFIG_SND_USB_AUDIO_MIDI_V2`. The first visible one is `CONFIG_SND_USB_AUDIO_MIDI_V2`, and when you choose it (to set `=y`), the core support for UMP (`CONFIG_SND_UMP`) and the sequencer binding (`CONFIG_SND_SEQ_UMP_CLIENT`) will be automatically selected.h](h=The following new configs are added for supporting MIDI 2.0: }(hjhhhNhNubhtitle_reference)}(h`CONFIG_SND_UMP`h]hCONFIG_SND_UMP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh, }(hjhhhNhNubj)}(h`CONFIG_SND_UMP_LEGACY_RAWMIDI`h]hCONFIG_SND_UMP_LEGACY_RAWMIDI}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh, }(hjhhhNhNubj)}(h`CONFIG_SND_SEQ_UMP`h]hCONFIG_SND_SEQ_UMP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh, }hjsbj)}(h`CONFIG_SND_SEQ_UMP_CLIENT`h]hCONFIG_SND_SEQ_UMP_CLIENT}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh, and }(hjhhhNhNubj)}(h`CONFIG_SND_USB_AUDIO_MIDI_V2`h]hCONFIG_SND_USB_AUDIO_MIDI_V2}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh. The first visible one is }(hjhhhNhNubj)}(h`CONFIG_SND_USB_AUDIO_MIDI_V2`h]hCONFIG_SND_USB_AUDIO_MIDI_V2}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh!, and when you choose it (to set }(hjhhhNhNubj)}(h`=y`h]h=y}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh), the core support for UMP (}(hjhhhNhNubj)}(h`CONFIG_SND_UMP`h]hCONFIG_SND_UMP}(hjGhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh) and the sequencer binding (}(hjhhhNhNubj)}(h`CONFIG_SND_SEQ_UMP_CLIENT`h]hCONFIG_SND_SEQ_UMP_CLIENT}(hjYhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh!) will be automatically selected.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK2hjhhubh)}(hyAdditionally, `CONFIG_SND_UMP_LEGACY_RAWMIDI=y` will enable the support for the legacy raw MIDI device for UMP Endpoints.h](hAdditionally, }(hjqhhhNhNubj)}(h!`CONFIG_SND_UMP_LEGACY_RAWMIDI=y`h]hCONFIG_SND_UMP_LEGACY_RAWMIDI=y}(hjyhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjqubhJ will enable the support for the legacy raw MIDI device for UMP Endpoints.}(hjqhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK:hjhhubeh}(h]kernel-configurationah ]h"]kernel configurationah$]h&]uh1hhhhhhhhK0ubh)}(hhh](h)}(h Rawmidi Device with USB MIDI 2.0h]h Rawmidi Device with USB MIDI 2.0}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK?ubh)}(hXKWhen a device supports MIDI 2.0, the USB-audio driver probes and uses the MIDI 2.0 interface (that is found always at the altset 1) as default instead of the MIDI 1.0 interface (at altset 0). You can switch back to the binding with the old MIDI 1.0 interface by passing `midi2_enable=0` option to snd-usb-audio driver module, too.h](hXWhen a device supports MIDI 2.0, the USB-audio driver probes and uses the MIDI 2.0 interface (that is found always at the altset 1) as default instead of the MIDI 1.0 interface (at altset 0). You can switch back to the binding with the old MIDI 1.0 interface by passing }(hjhhhNhNubj)}(h`midi2_enable=0`h]hmidi2_enable=0}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh, option to snd-usb-audio driver module, too.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKAhjhhubh)}(hXThe USB audio driver tries to query the UMP Endpoint and UMP Function Block information that are provided since UMP v1.1, and builds up the topology based on those information. When the device is older and doesn't respond to the new UMP inquiries, the driver falls back and builds the topology based on Group Terminal Block (GTB) information from the USB descriptor. Some device might be screwed up by the unexpected UMP command; in such a case, pass `midi2_ump_probe=0` option to snd-usb-audio driver for skipping the UMP v1.1 inquiries.h](hXThe USB audio driver tries to query the UMP Endpoint and UMP Function Block information that are provided since UMP v1.1, and builds up the topology based on those information. When the device is older and doesn’t respond to the new UMP inquiries, the driver falls back and builds the topology based on Group Terminal Block (GTB) information from the USB descriptor. Some device might be screwed up by the unexpected UMP command; in such a case, pass }(hjhhhNhNubj)}(h`midi2_ump_probe=0`h]hmidi2_ump_probe=0}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhD option to snd-usb-audio driver for skipping the UMP v1.1 inquiries.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKGhjhhubh)}(hXBWhen the MIDI 2.0 device is probed, the kernel creates a rawmidi device for each UMP Endpoint of the device. Its device name is `/dev/snd/umpC*D*` and different from the standard rawmidi device name `/dev/snd/midiC*D*` for MIDI 1.0, in order to avoid confusing the legacy applications accessing mistakenly to UMP devices.h](hWhen the MIDI 2.0 device is probed, the kernel creates a rawmidi device for each UMP Endpoint of the device. Its device name is }(hjhhhNhNubj)}(h`/dev/snd/umpC*D*`h]h/dev/snd/umpC*D*}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh5 and different from the standard rawmidi device name }(hjhhhNhNubj)}(h`/dev/snd/midiC*D*`h]h/dev/snd/midiC*D*}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhg for MIDI 1.0, in order to avoid confusing the legacy applications accessing mistakenly to UMP devices.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKPhjhhubh)}(hYou can read and write UMP packet data directly from/to this UMP rawmidi device. For example, reading via `hexdump` like below will show the incoming UMP packets of the card 0 device 0 in the hex format::h](hkYou can read and write UMP packet data directly from/to this UMP rawmidi device. For example, reading via }(hjhhhNhNubj)}(h `hexdump`h]hhexdump}(hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhX like below will show the incoming UMP packets of the card 0 device 0 in the hex format:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKVhjhhubh literal_block)}(hl% hexdump -C /dev/snd/umpC0D0 00000000 01 07 b0 20 00 07 b0 20 64 3c 90 20 64 3c 80 20 |... ... d<. d<. |h]hl% hexdump -C /dev/snd/umpC0D0 00000000 01 07 b0 20 00 07 b0 20 64 3c 90 20 64 3c 80 20 |... ... d<. d<. |}hj>sbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1j<hhhK[hjhhubh)}(hUnlike the MIDI 1.0 byte stream, UMP is a 32bit packet, and the size for reading or writing the device is also aligned to 32bit (which is 4 bytes).h]hUnlike the MIDI 1.0 byte stream, UMP is a 32bit packet, and the size for reading or writing the device is also aligned to 32bit (which is 4 bytes).}(hjNhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK^hjhhubh)}(hThe 32-bit words in the UMP packet payload are always in CPU native endianness. Transport drivers are responsible to convert UMP words from / to system endianness to required transport endianness / byte order.h]hThe 32-bit words in the UMP packet payload are always in CPU native endianness. Transport drivers are responsible to convert UMP words from / to system endianness to required transport endianness / byte order.}(hj\hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKbhjhhubh)}(hXWhen `CONFIG_SND_UMP_LEGACY_RAWMIDI` is set, the driver creates another standard raw MIDI device additionally as `/dev/snd/midiC*D*`. This contains 16 substreams, and each substream corresponds to a (0-based) UMP Group. Legacy applications can access to the specified group via each substream in MIDI 1.0 byte stream format. With the ALSA rawmidi API, you can open the arbitrary substream, while just opening `/dev/snd/midiC*D*` will end up with opening the first substream.h](hWhen }(hjjhhhNhNubj)}(h`CONFIG_SND_UMP_LEGACY_RAWMIDI`h]hCONFIG_SND_UMP_LEGACY_RAWMIDI}(hjrhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjjubhM is set, the driver creates another standard raw MIDI device additionally as }(hjjhhhNhNubj)}(h`/dev/snd/midiC*D*`h]h/dev/snd/midiC*D*}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjjubhX. This contains 16 substreams, and each substream corresponds to a (0-based) UMP Group. Legacy applications can access to the specified group via each substream in MIDI 1.0 byte stream format. With the ALSA rawmidi API, you can open the arbitrary substream, while just opening }(hjjhhhNhNubj)}(h`/dev/snd/midiC*D*`h]h/dev/snd/midiC*D*}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjjubh. will end up with opening the first substream.}(hjjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKghjhhubh)}(hX/Each UMP Endpoint can provide the additional information, constructed from the information inquired via UMP 1.1 Stream messages or USB MIDI 2.0 descriptors. And a UMP Endpoint may contain one or more UMP Blocks, where UMP Block is an abstraction introduced in the ALSA UMP implementations to represent the associations among UMP Groups. UMP Block corresponds to Function Block in UMP 1.1 specification. When UMP 1.1 Function Block information isn't available, it's filled partially from Group Terminal Block (GTB) as defined in USB MIDI 2.0 specifications.h]hX3Each UMP Endpoint can provide the additional information, constructed from the information inquired via UMP 1.1 Stream messages or USB MIDI 2.0 descriptors. And a UMP Endpoint may contain one or more UMP Blocks, where UMP Block is an abstraction introduced in the ALSA UMP implementations to represent the associations among UMP Groups. UMP Block corresponds to Function Block in UMP 1.1 specification. When UMP 1.1 Function Block information isn’t available, it’s filled partially from Group Terminal Block (GTB) as defined in USB MIDI 2.0 specifications.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKphjhhubh)}(huThe information of UMP Endpoints and UMP Blocks are found in the proc file `/proc/asound/card*/midi*`. For example::h](hKThe information of UMP Endpoints and UMP Blocks are found in the proc file }(hjhhhNhNubj)}(h`/proc/asound/card*/midi*`h]h/proc/asound/card*/midi*}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh. For example:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKzhjhhubj=)}(hX% cat /proc/asound/card1/midi0 ProtoZOA MIDI Type: UMP EP Name: ProtoZOA EP Product ID: ABCD12345678 UMP Version: 0x0000 Protocol Caps: 0x00000100 Protocol: 0x00000100 Num Blocks: 3 Block 0 (ProtoZOA Main) Direction: bidirection Active: Yes Groups: 1-1 Is MIDI1: No Block 1 (ProtoZOA Ext IN) Direction: output Active: Yes Groups: 2-2 Is MIDI1: Yes (Low Speed) ....h]hX% cat /proc/asound/card1/midi0 ProtoZOA MIDI Type: UMP EP Name: ProtoZOA EP Product ID: ABCD12345678 UMP Version: 0x0000 Protocol Caps: 0x00000100 Protocol: 0x00000100 Num Blocks: 3 Block 0 (ProtoZOA Main) Direction: bidirection Active: Yes Groups: 1-1 Is MIDI1: No Block 1 (ProtoZOA Ext IN) Direction: output Active: Yes Groups: 2-2 Is MIDI1: Yes (Low Speed) ....}hjsbah}(h]h ]h"]h$]h&]jLjMuh1j<hhhK}hjhhubh)}(hhNote that `Groups` field shown in the proc file above indicates the 1-based UMP Group numbers (from-to).h](h Note that }(hjhhhNhNubj)}(h`Groups`h]hGroups}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhV field shown in the proc file above indicates the 1-based UMP Group numbers (from-to).}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hThose additional UMP Endpoint and UMP Block information can be obtained via the new ioctls `SNDRV_UMP_IOCTL_ENDPOINT_INFO` and `SNDRV_UMP_IOCTL_BLOCK_INFO`, respectively.h](h[Those additional UMP Endpoint and UMP Block information can be obtained via the new ioctls }(hj hhhNhNubj)}(h`SNDRV_UMP_IOCTL_ENDPOINT_INFO`h]hSNDRV_UMP_IOCTL_ENDPOINT_INFO}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh and }(hj hhhNhNubj)}(h`SNDRV_UMP_IOCTL_BLOCK_INFO`h]hSNDRV_UMP_IOCTL_BLOCK_INFO}(hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh, respectively.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXThe rawmidi name and the UMP Endpoint name are usually identical, and in the case of USB MIDI, it's taken from `iInterface` of the corresponding USB MIDI interface descriptor. If it's not provided, it's copied from `iProduct` of the USB device descriptor as a fallback.h](hqThe rawmidi name and the UMP Endpoint name are usually identical, and in the case of USB MIDI, it’s taken from }(hj<hhhNhNubj)}(h `iInterface`h]h iInterface}(hjDhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj<ubha of the corresponding USB MIDI interface descriptor. If it’s not provided, it’s copied from }(hj<hhhNhNubj)}(h `iProduct`h]hiProduct}(hjVhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj<ubh, of the USB device descriptor as a fallback.}(hj<hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hThe Endpoint Product ID is a string field and supposed to be unique. It's copied from `iSerialNumber` of the device for USB MIDI.h](hXThe Endpoint Product ID is a string field and supposed to be unique. It’s copied from }(hjnhhhNhNubj)}(h`iSerialNumber`h]h iSerialNumber}(hjvhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjnubh of the device for USB MIDI.}(hjnhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hQThe protocol capabilities and the actual protocol bits are defined in `asound.h`.h](hFThe protocol capabilities and the actual protocol bits are defined in }(hjhhhNhNubj)}(h `asound.h`h]hasound.h}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h] rawmidi-device-with-usb-midi-2-0ah ]h"] rawmidi device with usb midi 2.0ah$]h&]uh1hhhhhhhhK?ubh)}(hhh](h)}(h ALSA Sequencer with USB MIDI 2.0h]h ALSA Sequencer with USB MIDI 2.0}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hXIn addition to the rawmidi interfaces, ALSA sequencer interface supports the new UMP MIDI 2.0 device, too. Now, each ALSA sequencer client may set its MIDI version (0, 1 or 2) to declare itself being either the legacy, UMP MIDI 1.0 or UMP MIDI 2.0 device, respectively. The first, legacy client is the one that sends/receives the old sequencer event as was. Meanwhile, UMP MIDI 1.0 and 2.0 clients send and receive in the extended event record for UMP. The MIDI version is seen in the new `midi_version` field of `snd_seq_client_info`.h](hXIn addition to the rawmidi interfaces, ALSA sequencer interface supports the new UMP MIDI 2.0 device, too. Now, each ALSA sequencer client may set its MIDI version (0, 1 or 2) to declare itself being either the legacy, UMP MIDI 1.0 or UMP MIDI 2.0 device, respectively. The first, legacy client is the one that sends/receives the old sequencer event as was. Meanwhile, UMP MIDI 1.0 and 2.0 clients send and receive in the extended event record for UMP. The MIDI version is seen in the new }(hjhhhNhNubj)}(h`midi_version`h]h midi_version}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh field of }(hjhhhNhNubj)}(h`snd_seq_client_info`h]hsnd_seq_client_info}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hX[A UMP packet can be sent/received in a sequencer event embedded by specifying the new event flag bit `SNDRV_SEQ_EVENT_UMP`. When this flag is set, the event has 16 byte (128 bit) data payload for holding the UMP packet. Without the `SNDRV_SEQ_EVENT_UMP` bit flag, the event is treated as a legacy event as it was (with max 12 byte data payload).h](heA UMP packet can be sent/received in a sequencer event embedded by specifying the new event flag bit }(hjhhhNhNubj)}(h`SNDRV_SEQ_EVENT_UMP`h]hSNDRV_SEQ_EVENT_UMP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhp. When this flag is set, the event has 16 byte (128 bit) data payload for holding the UMP packet. Without the }(hjhhhNhNubj)}(h`SNDRV_SEQ_EVENT_UMP`h]hSNDRV_SEQ_EVENT_UMP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh\ bit flag, the event is treated as a legacy event as it was (with max 12 byte data payload).}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hWith `SNDRV_SEQ_EVENT_UMP` flag set, the type field of a UMP sequencer event is ignored (but it should be set to 0 as default).h](hWith }(hj+hhhNhNubj)}(h`SNDRV_SEQ_EVENT_UMP`h]hSNDRV_SEQ_EVENT_UMP}(hj3hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj+ubhe flag set, the type field of a UMP sequencer event is ignored (but it should be set to 0 as default).}(hj+hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hPThe type of each client can be seen in `/proc/asound/seq/clients`. For example::h](h'The type of each client can be seen in }(hjKhhhNhNubj)}(h`/proc/asound/seq/clients`h]h/proc/asound/seq/clients}(hjShhhNhNubah}(h]h ]h"]h$]h&]uh1jhjKubh. For example:}(hjKhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj=)}(hX0% cat /proc/asound/seq/clients Client info cur clients : 3 .... Client 14 : "Midi Through" [Kernel Legacy] Port 0 : "Midi Through Port-0" (RWe-) Client 20 : "ProtoZOA" [Kernel UMP MIDI1] UMP Endpoint: ProtoZOA UMP Block 0: ProtoZOA Main [Active] Groups: 1-1 UMP Block 1: ProtoZOA Ext IN [Active] Groups: 2-2 UMP Block 2: ProtoZOA Ext OUT [Active] Groups: 3-3 Port 0 : "MIDI 2.0" (RWeX) [In/Out] Port 1 : "ProtoZOA Main" (RWeX) [In/Out] Port 2 : "ProtoZOA Ext IN" (-We-) [Out] Port 3 : "ProtoZOA Ext OUT" (R-e-) [In]h]hX0% cat /proc/asound/seq/clients Client info cur clients : 3 .... Client 14 : "Midi Through" [Kernel Legacy] Port 0 : "Midi Through Port-0" (RWe-) Client 20 : "ProtoZOA" [Kernel UMP MIDI1] UMP Endpoint: ProtoZOA UMP Block 0: ProtoZOA Main [Active] Groups: 1-1 UMP Block 1: ProtoZOA Ext IN [Active] Groups: 2-2 UMP Block 2: ProtoZOA Ext OUT [Active] Groups: 3-3 Port 0 : "MIDI 2.0" (RWeX) [In/Out] Port 1 : "ProtoZOA Main" (RWeX) [In/Out] Port 2 : "ProtoZOA Ext IN" (-We-) [Out] Port 3 : "ProtoZOA Ext OUT" (R-e-) [In]}hjksbah}(h]h ]h"]h$]h&]jLjMuh1j<hhhKhjhhubh)}(hXHere you can find two types of kernel clients, "Legacy" for client 14, and "UMP MIDI1" for client 20, which is a USB MIDI 2.0 device. A USB MIDI 2.0 client gives always the port 0 as "MIDI 2.0" and the rest ports from 1 for each UMP Group (e.g. port 1 for Group 1). In this example, the device has three active groups (Main, Ext IN and Ext OUT), and those are exposed as sequencer ports from 1 to 3. The "MIDI 2.0" port is for a UMP Endpoint, and its difference from other UMP Group ports is that UMP Endpoint port sends the events from the all ports on the device ("catch-all"), while each UMP Group port sends only the events from the given UMP Group. Also, UMP groupless messages (such as the UMP message type 0x0f) are sent only to the UMP Endpoint port.h]hX Here you can find two types of kernel clients, “Legacy” for client 14, and “UMP MIDI1” for client 20, which is a USB MIDI 2.0 device. A USB MIDI 2.0 client gives always the port 0 as “MIDI 2.0” and the rest ports from 1 for each UMP Group (e.g. port 1 for Group 1). In this example, the device has three active groups (Main, Ext IN and Ext OUT), and those are exposed as sequencer ports from 1 to 3. The “MIDI 2.0” port is for a UMP Endpoint, and its difference from other UMP Group ports is that UMP Endpoint port sends the events from the all ports on the device (“catch-all”), while each UMP Group port sends only the events from the given UMP Group. Also, UMP groupless messages (such as the UMP message type 0x0f) are sent only to the UMP Endpoint port.}(hjyhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hX9Note that, although each UMP sequencer client usually creates 16 ports, those ports that don't belong to any UMP Blocks (or belonging to inactive UMP Blocks) are marked as inactive, and they don't appear in the proc outputs. In the example above, the sequencer ports from 4 to 16 are present but not shown there.h]hX=Note that, although each UMP sequencer client usually creates 16 ports, those ports that don’t belong to any UMP Blocks (or belonging to inactive UMP Blocks) are marked as inactive, and they don’t appear in the proc outputs. In the example above, the sequencer ports from 4 to 16 are present but not shown there.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hThe proc file above shows the UMP Block information, too. The same entry (but with more detailed information) is found in the rawmidi proc output.h]hThe proc file above shows the UMP Block information, too. The same entry (but with more detailed information) is found in the rawmidi proc output.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXjWhen clients are connected between different MIDI versions, the events are translated automatically depending on the client's version, not only between the legacy and the UMP MIDI 1.0/2.0 types, but also between UMP MIDI 1.0 and 2.0 types, too. For example, running `aseqdump` program on the ProtoZOA Main port in the legacy mode will give you the output like::h](hX When clients are connected between different MIDI versions, the events are translated automatically depending on the client’s version, not only between the legacy and the UMP MIDI 1.0/2.0 types, but also between UMP MIDI 1.0 and 2.0 types, too. For example, running }(hjhhhNhNubj)}(h `aseqdump`h]haseqdump}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhT program on the ProtoZOA Main port in the legacy mode will give you the output like:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj=)}(hX % aseqdump -p 20:1 Waiting for data. Press Ctrl+C to end. Source Event Ch Data 20:1 Note on 0, note 60, velocity 100 20:1 Note off 0, note 60, velocity 100 20:1 Control change 0, controller 11, value 4h]hX % aseqdump -p 20:1 Waiting for data. Press Ctrl+C to end. Source Event Ch Data 20:1 Note on 0, note 60, velocity 100 20:1 Note off 0, note 60, velocity 100 20:1 Control change 0, controller 11, value 4}hjsbah}(h]h ]h"]h$]h&]jLjMuh1j<hhhKhjhhubh)}(hVWhen you run `aseqdump` in MIDI 2.0 mode, it'll receive the high precision data like::h](h When you run }(hjhhhNhNubj)}(h `aseqdump`h]haseqdump}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh@ in MIDI 2.0 mode, it’ll receive the high precision data like:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj=)}(hXV% aseqdump -u 2 -p 20:1 Waiting for data. Press Ctrl+C to end. Source Event Ch Data 20:1 Note on 0, note 60, velocity 0xc924, attr type = 0, data = 0x0 20:1 Note off 0, note 60, velocity 0xc924, attr type = 0, data = 0x0 20:1 Control change 0, controller 11, value 0x2000000h]hXV% aseqdump -u 2 -p 20:1 Waiting for data. Press Ctrl+C to end. Source Event Ch Data 20:1 Note on 0, note 60, velocity 0xc924, attr type = 0, data = 0x0 20:1 Note off 0, note 60, velocity 0xc924, attr type = 0, data = 0x0 20:1 Control change 0, controller 11, value 0x2000000}hjsbah}(h]h ]h"]h$]h&]jLjMuh1j<hhhKhjhhubh)}(hAwhile the data is automatically converted by ALSA sequencer core.h]hAwhile the data is automatically converted by ALSA sequencer core.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h] alsa-sequencer-with-usb-midi-2-0ah ]h"] alsa sequencer with usb midi 2.0ah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hRawmidi API Extensionsh]hRawmidi API Extensions}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hhh](h)}(hXThe additional UMP Endpoint information can be obtained via the new ioctl `SNDRV_UMP_IOCTL_ENDPOINT_INFO`. It contains the associated card and device numbers, the bit flags, the protocols, the number of UMP Blocks, the name string of the endpoint, etc. The protocols are specified in two field, the protocol capabilities and the current protocol. Both contain the bit flags specifying the MIDI protocol version (`SNDRV_UMP_EP_INFO_PROTO_MIDI1` or `SNDRV_UMP_EP_INFO_PROTO_MIDI2`) in the upper byte and the jitter reduction timestamp (`SNDRV_UMP_EP_INFO_PROTO_JRTS_TX` and `SNDRV_UMP_EP_INFO_PROTO_JRTS_RX`) in the lower byte. A UMP Endpoint may contain up to 32 UMP Blocks, and the number of the currently assigned blocks are shown in the Endpoint information. h](h)}(hThe additional UMP Endpoint information can be obtained via the new ioctl `SNDRV_UMP_IOCTL_ENDPOINT_INFO`. It contains the associated card and device numbers, the bit flags, the protocols, the number of UMP Blocks, the name string of the endpoint, etc.h](hJThe additional UMP Endpoint information can be obtained via the new ioctl }(hj-hhhNhNubj)}(h`SNDRV_UMP_IOCTL_ENDPOINT_INFO`h]hSNDRV_UMP_IOCTL_ENDPOINT_INFO}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj-ubh. It contains the associated card and device numbers, the bit flags, the protocols, the number of UMP Blocks, the name string of the endpoint, etc.}(hj-hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM hj)ubh)}(hXuThe protocols are specified in two field, the protocol capabilities and the current protocol. Both contain the bit flags specifying the MIDI protocol version (`SNDRV_UMP_EP_INFO_PROTO_MIDI1` or `SNDRV_UMP_EP_INFO_PROTO_MIDI2`) in the upper byte and the jitter reduction timestamp (`SNDRV_UMP_EP_INFO_PROTO_JRTS_TX` and `SNDRV_UMP_EP_INFO_PROTO_JRTS_RX`) in the lower byte.h](hThe protocols are specified in two field, the protocol capabilities and the current protocol. Both contain the bit flags specifying the MIDI protocol version (}(hjMhhhNhNubj)}(h`SNDRV_UMP_EP_INFO_PROTO_MIDI1`h]hSNDRV_UMP_EP_INFO_PROTO_MIDI1}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjMubh or }(hjMhhhNhNubj)}(h`SNDRV_UMP_EP_INFO_PROTO_MIDI2`h]hSNDRV_UMP_EP_INFO_PROTO_MIDI2}(hjghhhNhNubah}(h]h ]h"]h$]h&]uh1jhjMubh8) in the upper byte and the jitter reduction timestamp (}(hjMhhhNhNubj)}(h!`SNDRV_UMP_EP_INFO_PROTO_JRTS_TX`h]hSNDRV_UMP_EP_INFO_PROTO_JRTS_TX}(hjyhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjMubh and }(hjMhhhNhNubj)}(h!`SNDRV_UMP_EP_INFO_PROTO_JRTS_RX`h]hSNDRV_UMP_EP_INFO_PROTO_JRTS_RX}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjMubh) in the lower byte.}(hjMhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj)ubh)}(hA UMP Endpoint may contain up to 32 UMP Blocks, and the number of the currently assigned blocks are shown in the Endpoint information.h]hA UMP Endpoint may contain up to 32 UMP Blocks, and the number of the currently assigned blocks are shown in the Endpoint information.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj)ubeh}(h]h ]h"]h$]h&]uh1hhj&hhhhhNubh)}(hXEach UMP Block information can be obtained via another new ioctl `SNDRV_UMP_IOCTL_BLOCK_INFO`. The block ID number (0-based) has to be passed for the block to query. The received data contains the associated the direction of the block, the first associated group ID (0-based) and the number of groups, the name string of the block, etc. The direction is either `SNDRV_UMP_DIR_INPUT`, `SNDRV_UMP_DIR_OUTPUT` or `SNDRV_UMP_DIR_BIDIRECTION`. h](h)}(hXREach UMP Block information can be obtained via another new ioctl `SNDRV_UMP_IOCTL_BLOCK_INFO`. The block ID number (0-based) has to be passed for the block to query. The received data contains the associated the direction of the block, the first associated group ID (0-based) and the number of groups, the name string of the block, etc.h](hAEach UMP Block information can be obtained via another new ioctl }(hjhhhNhNubj)}(h`SNDRV_UMP_IOCTL_BLOCK_INFO`h]hSNDRV_UMP_IOCTL_BLOCK_INFO}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh. The block ID number (0-based) has to be passed for the block to query. The received data contains the associated the direction of the block, the first associated group ID (0-based) and the number of groups, the name string of the block, etc.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubh)}(heThe direction is either `SNDRV_UMP_DIR_INPUT`, `SNDRV_UMP_DIR_OUTPUT` or `SNDRV_UMP_DIR_BIDIRECTION`.h](hThe direction is either }(hjhhhNhNubj)}(h`SNDRV_UMP_DIR_INPUT`h]hSNDRV_UMP_DIR_INPUT}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh, }(hjhhhNhNubj)}(h`SNDRV_UMP_DIR_OUTPUT`h]hSNDRV_UMP_DIR_OUTPUT}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh or }(hjhhhNhNubj)}(h`SNDRV_UMP_DIR_BIDIRECTION`h]hSNDRV_UMP_DIR_BIDIRECTION}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM hjubeh}(h]h ]h"]h$]h&]uh1hhj&hhhhhNubh)}(hXFor the device supports UMP v1.1, the UMP MIDI protocol can be switched via "Stream Configuration Request" message (UMP type 0x0f, status 0x05). When UMP core receives such a message, it updates the UMP EP info and the corresponding sequencer clients as well. h]h)}(hXFor the device supports UMP v1.1, the UMP MIDI protocol can be switched via "Stream Configuration Request" message (UMP type 0x0f, status 0x05). When UMP core receives such a message, it updates the UMP EP info and the corresponding sequencer clients as well.h]hXFor the device supports UMP v1.1, the UMP MIDI protocol can be switched via “Stream Configuration Request” message (UMP type 0x0f, status 0x05). When UMP core receives such a message, it updates the UMP EP info and the corresponding sequencer clients as well.}(hj)hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM#hj%ubah}(h]h ]h"]h$]h&]uh1hhj&hhhhhNubh)}(hThe legacy rawmidi device number is found in the new `tied_device` field of the rawmidi info. On the other hand, the UMP rawmidi device number is found in `tied_device` field of the legacy rawmidi info, too. h]h)}(hThe legacy rawmidi device number is found in the new `tied_device` field of the rawmidi info. On the other hand, the UMP rawmidi device number is found in `tied_device` field of the legacy rawmidi info, too.h](h5The legacy rawmidi device number is found in the new }(hjAhhhNhNubj)}(h `tied_device`h]h tied_device}(hjIhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjAubhY field of the rawmidi info. On the other hand, the UMP rawmidi device number is found in }(hjAhhhNhNubj)}(h `tied_device`h]h tied_device}(hj[hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjAubh' field of the legacy rawmidi info, too.}(hjAhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM(hj=ubah}(h]h ]h"]h$]h&]uh1hhj&hhhhhNubh)}(hX Each substream of the legacy rawmidi may be enabled / disabled dynamically depending on the UMP FB state. When the selected substream is inactive, it's indicated by the bit 0x10 (`SNDRV_RAWMIDI_INFO_STREAM_INACTIVE`) in the `flags` field of the legacy rawmidi info. h]h)}(hX Each substream of the legacy rawmidi may be enabled / disabled dynamically depending on the UMP FB state. When the selected substream is inactive, it's indicated by the bit 0x10 (`SNDRV_RAWMIDI_INFO_STREAM_INACTIVE`) in the `flags` field of the legacy rawmidi info.h](hEach substream of the legacy rawmidi may be enabled / disabled dynamically depending on the UMP FB state. When the selected substream is inactive, it’s indicated by the bit 0x10 (}(hj}hhhNhNubj)}(h$`SNDRV_RAWMIDI_INFO_STREAM_INACTIVE`h]h"SNDRV_RAWMIDI_INFO_STREAM_INACTIVE}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj}ubh ) in the }(hj}hhhNhNubj)}(h`flags`h]hflags}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj}ubh" field of the legacy rawmidi info.}(hj}hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM-hjyubah}(h]h ]h"]h$]h&]uh1hhj&hhhhhNubeh}(h]h ]h"]h$]h&]jB*uh1hhhhM hjhhubeh}(h]rawmidi-api-extensionsah ]h"]rawmidi api extensionsah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(hControl API Extensionsh]hControl API Extensions}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhM5ubh)}(hhh](h)}(hX^The new ioctl `SNDRV_CTL_IOCTL_UMP_NEXT_DEVICE` is introduced for querying the next UMP rawmidi device, while the existing ioctl `SNDRV_CTL_IOCTL_RAWMIDI_NEXT_DEVICE` queries only the legacy rawmidi devices. For setting the subdevice (substream number) to be opened, use the ioctl `SNDRV_CTL_IOCTL_RAWMIDI_PREFER_SUBDEVICE` like the normal rawmidi. h](h)}(hThe new ioctl `SNDRV_CTL_IOCTL_UMP_NEXT_DEVICE` is introduced for querying the next UMP rawmidi device, while the existing ioctl `SNDRV_CTL_IOCTL_RAWMIDI_NEXT_DEVICE` queries only the legacy rawmidi devices.h](hThe new ioctl }(hjhhhNhNubj)}(h!`SNDRV_CTL_IOCTL_UMP_NEXT_DEVICE`h]hSNDRV_CTL_IOCTL_UMP_NEXT_DEVICE}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhR is introduced for querying the next UMP rawmidi device, while the existing ioctl }(hjhhhNhNubj)}(h%`SNDRV_CTL_IOCTL_RAWMIDI_NEXT_DEVICE`h]h#SNDRV_CTL_IOCTL_RAWMIDI_NEXT_DEVICE}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh) queries only the legacy rawmidi devices.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM7hjubh)}(hFor setting the subdevice (substream number) to be opened, use the ioctl `SNDRV_CTL_IOCTL_RAWMIDI_PREFER_SUBDEVICE` like the normal rawmidi.h](hIFor setting the subdevice (substream number) to be opened, use the ioctl }(hjhhhNhNubj)}(h*`SNDRV_CTL_IOCTL_RAWMIDI_PREFER_SUBDEVICE`h]h(SNDRV_CTL_IOCTL_RAWMIDI_PREFER_SUBDEVICE}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh like the normal rawmidi.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM<hjubeh}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hXLTwo new ioctls `SNDRV_CTL_IOCTL_UMP_ENDPOINT_INFO` and `SNDRV_CTL_IOCTL_UMP_BLOCK_INFO` provide the UMP Endpoint and UMP Block information of the specified UMP device via ALSA control API without opening the actual (UMP) rawmidi device. The `card` field is ignored upon inquiry, always tied with the card of the control interface. h]h)}(hXJTwo new ioctls `SNDRV_CTL_IOCTL_UMP_ENDPOINT_INFO` and `SNDRV_CTL_IOCTL_UMP_BLOCK_INFO` provide the UMP Endpoint and UMP Block information of the specified UMP device via ALSA control API without opening the actual (UMP) rawmidi device. The `card` field is ignored upon inquiry, always tied with the card of the control interface.h](hTwo new ioctls }(hj8hhhNhNubj)}(h#`SNDRV_CTL_IOCTL_UMP_ENDPOINT_INFO`h]h!SNDRV_CTL_IOCTL_UMP_ENDPOINT_INFO}(hj@hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj8ubh and }(hj8hhhNhNubj)}(h `SNDRV_CTL_IOCTL_UMP_BLOCK_INFO`h]hSNDRV_CTL_IOCTL_UMP_BLOCK_INFO}(hjRhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj8ubh provide the UMP Endpoint and UMP Block information of the specified UMP device via ALSA control API without opening the actual (UMP) rawmidi device. The }(hj8hhhNhNubj)}(h`card`h]hcard}(hjdhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj8ubhS field is ignored upon inquiry, always tied with the card of the control interface.}(hj8hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM@hj4ubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubeh}(h]h ]h"]h$]h&]jBjuh1hhhhM7hjhhubeh}(h]control-api-extensionsah ]h"]control api extensionsah$]h&]uh1hhhhhhhhM5ubh)}(hhh](h)}(hSequencer API Extensionsh]hSequencer API Extensions}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMIubh)}(hhh](h)}(hX`midi_version` field is added to `snd_seq_client_info` to indicate the current MIDI version (either 0, 1 or 2) of each client. When `midi_version` is 1 or 2, the alignment of read from a UMP sequencer client is also changed from the former 28 bytes to 32 bytes for the extended payload. The alignment size for the write isn't changed, but each event size may differ depending on the new bit flag below. h]h)}(hX`midi_version` field is added to `snd_seq_client_info` to indicate the current MIDI version (either 0, 1 or 2) of each client. When `midi_version` is 1 or 2, the alignment of read from a UMP sequencer client is also changed from the former 28 bytes to 32 bytes for the extended payload. The alignment size for the write isn't changed, but each event size may differ depending on the new bit flag below.h](j)}(h`midi_version`h]h midi_version}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh field is added to }(hjhhhNhNubj)}(h`snd_seq_client_info`h]hsnd_seq_client_info}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhN to indicate the current MIDI version (either 0, 1 or 2) of each client. When }(hjhhhNhNubj)}(h`midi_version`h]h midi_version}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhX is 1 or 2, the alignment of read from a UMP sequencer client is also changed from the former 28 bytes to 32 bytes for the extended payload. The alignment size for the write isn’t changed, but each event size may differ depending on the new bit flag below.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMKhjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(h`SNDRV_SEQ_EVENT_UMP` flag bit is added for each sequencer event flags. When this bit flag is set, the sequencer event is extended to have a larger payload of 16 bytes instead of the legacy 12 bytes, and the event contains the UMP packet in the payload. h]h)}(h`SNDRV_SEQ_EVENT_UMP` flag bit is added for each sequencer event flags. When this bit flag is set, the sequencer event is extended to have a larger payload of 16 bytes instead of the legacy 12 bytes, and the event contains the UMP packet in the payload.h](j)}(h`SNDRV_SEQ_EVENT_UMP`h]hSNDRV_SEQ_EVENT_UMP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh flag bit is added for each sequencer event flags. When this bit flag is set, the sequencer event is extended to have a larger payload of 16 bytes instead of the legacy 12 bytes, and the event contains the UMP packet in the payload.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMShjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hgThe new sequencer port type bit (`SNDRV_SEQ_PORT_TYPE_MIDI_UMP`) indicates the port being UMP-capable. h]h)}(hfThe new sequencer port type bit (`SNDRV_SEQ_PORT_TYPE_MIDI_UMP`) indicates the port being UMP-capable.h](h!The new sequencer port type bit (}(hj hhhNhNubj)}(h`SNDRV_SEQ_PORT_TYPE_MIDI_UMP`h]hSNDRV_SEQ_PORT_TYPE_MIDI_UMP}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh') indicates the port being UMP-capable.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMXhj ubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hThe sequencer ports have new capability bits to indicate the inactive ports (`SNDRV_SEQ_PORT_CAP_INACTIVE`) and the UMP Endpoint port (`SNDRV_SEQ_PORT_CAP_UMP_ENDPOINT`). h]h)}(hThe sequencer ports have new capability bits to indicate the inactive ports (`SNDRV_SEQ_PORT_CAP_INACTIVE`) and the UMP Endpoint port (`SNDRV_SEQ_PORT_CAP_UMP_ENDPOINT`).h](hMThe sequencer ports have new capability bits to indicate the inactive ports (}(hjB hhhNhNubj)}(h`SNDRV_SEQ_PORT_CAP_INACTIVE`h]hSNDRV_SEQ_PORT_CAP_INACTIVE}(hjJ hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjB ubh) and the UMP Endpoint port (}(hjB hhhNhNubj)}(h!`SNDRV_SEQ_PORT_CAP_UMP_ENDPOINT`h]hSNDRV_SEQ_PORT_CAP_UMP_ENDPOINT}(hj\ hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjB ubh).}(hjB hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM[hj> ubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hThe event conversion of ALSA sequencer clients can be suppressed the new filter bit `SNDRV_SEQ_FILTER_NO_CONVERT` set to the client info. For example, the kernel pass-through client (`snd-seq-dummy`) sets this flag internally. h]h)}(hThe event conversion of ALSA sequencer clients can be suppressed the new filter bit `SNDRV_SEQ_FILTER_NO_CONVERT` set to the client info. For example, the kernel pass-through client (`snd-seq-dummy`) sets this flag internally.h](hTThe event conversion of ALSA sequencer clients can be suppressed the new filter bit }(hj~ hhhNhNubj)}(h`SNDRV_SEQ_FILTER_NO_CONVERT`h]hSNDRV_SEQ_FILTER_NO_CONVERT}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj~ ubhF set to the client info. For example, the kernel pass-through client (}(hj~ hhhNhNubj)}(h`snd-seq-dummy`h]h snd-seq-dummy}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj~ ubh) sets this flag internally.}(hj~ hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM_hjz ubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hThe port information gained the new field `direction` to indicate the direction of the port (either `SNDRV_SEQ_PORT_DIR_INPUT`, `SNDRV_SEQ_PORT_DIR_OUTPUT` or `SNDRV_SEQ_PORT_DIR_BIDIRECTION`). h]h)}(hThe port information gained the new field `direction` to indicate the direction of the port (either `SNDRV_SEQ_PORT_DIR_INPUT`, `SNDRV_SEQ_PORT_DIR_OUTPUT` or `SNDRV_SEQ_PORT_DIR_BIDIRECTION`).h](h*The port information gained the new field }(hj hhhNhNubj)}(h `direction`h]h direction}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh/ to indicate the direction of the port (either }(hj hhhNhNubj)}(h`SNDRV_SEQ_PORT_DIR_INPUT`h]hSNDRV_SEQ_PORT_DIR_INPUT}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh, }(hj hhhNhNubj)}(h`SNDRV_SEQ_PORT_DIR_OUTPUT`h]hSNDRV_SEQ_PORT_DIR_OUTPUT}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh or }(hj hhhNhNubj)}(h `SNDRV_SEQ_PORT_DIR_BIDIRECTION`h]hSNDRV_SEQ_PORT_DIR_BIDIRECTION}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh).}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMdhj ubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hXcAnother additional field for the port information is `ump_group` which specifies the associated UMP Group Number (1-based). When it's non-zero, the UMP group field in the UMP packet updated upon delivery to the specified group (corrected to be 0-based). Each sequencer port is supposed to set this field if it's a port to specific to a certain UMP group. h]h)}(hXbAnother additional field for the port information is `ump_group` which specifies the associated UMP Group Number (1-based). When it's non-zero, the UMP group field in the UMP packet updated upon delivery to the specified group (corrected to be 0-based). Each sequencer port is supposed to set this field if it's a port to specific to a certain UMP group.h](h5Another additional field for the port information is }(hj hhhNhNubj)}(h `ump_group`h]h ump_group}(hj" hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubhX& which specifies the associated UMP Group Number (1-based). When it’s non-zero, the UMP group field in the UMP packet updated upon delivery to the specified group (corrected to be 0-based). Each sequencer port is supposed to set this field if it’s a port to specific to a certain UMP group.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhhj ubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hXCEach client may set the additional event filter for UMP Groups in `group_filter` bitmap. The filter consists of bitmap from 1-based Group numbers. For example, when the bit 1 is set, messages from Group 1 (i.e. the very first group) are filtered and not delivered. The bit 0 is used for filtering UMP groupless messages. h]h)}(hXBEach client may set the additional event filter for UMP Groups in `group_filter` bitmap. The filter consists of bitmap from 1-based Group numbers. For example, when the bit 1 is set, messages from Group 1 (i.e. the very first group) are filtered and not delivered. The bit 0 is used for filtering UMP groupless messages.h](hBEach client may set the additional event filter for UMP Groups in }(hjD hhhNhNubj)}(h`group_filter`h]h group_filter}(hjL hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjD ubh bitmap. The filter consists of bitmap from 1-based Group numbers. For example, when the bit 1 is set, messages from Group 1 (i.e. the very first group) are filtered and not delivered. The bit 0 is used for filtering UMP groupless messages.}(hjD hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMohj@ ubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hXRTwo new ioctls are added for UMP-capable clients: `SNDRV_SEQ_IOCTL_GET_CLIENT_UMP_INFO` and `SNDRV_SEQ_IOCTL_SET_CLIENT_UMP_INFO`. They are used to get and set either `snd_ump_endpoint_info` or `snd_ump_block_info` data associated with the sequencer client. The USB MIDI driver provides those information from the underlying UMP rawmidi, while a user-space client may provide its own data via `*_SET` ioctl. For an Endpoint data, pass 0 to the `type` field, while for a Block data, pass the block number + 1 to the `type` field. Setting the data for a kernel client shall result in an error. h]h)}(hXQTwo new ioctls are added for UMP-capable clients: `SNDRV_SEQ_IOCTL_GET_CLIENT_UMP_INFO` and `SNDRV_SEQ_IOCTL_SET_CLIENT_UMP_INFO`. They are used to get and set either `snd_ump_endpoint_info` or `snd_ump_block_info` data associated with the sequencer client. The USB MIDI driver provides those information from the underlying UMP rawmidi, while a user-space client may provide its own data via `*_SET` ioctl. For an Endpoint data, pass 0 to the `type` field, while for a Block data, pass the block number + 1 to the `type` field. Setting the data for a kernel client shall result in an error.h](h2Two new ioctls are added for UMP-capable clients: }(hjn hhhNhNubj)}(h%`SNDRV_SEQ_IOCTL_GET_CLIENT_UMP_INFO`h]h#SNDRV_SEQ_IOCTL_GET_CLIENT_UMP_INFO}(hjv hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjn ubh and }(hjn hhhNhNubj)}(h%`SNDRV_SEQ_IOCTL_SET_CLIENT_UMP_INFO`h]h#SNDRV_SEQ_IOCTL_SET_CLIENT_UMP_INFO}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjn ubh'. They are used to get and set either }(hjn hhhNhNubj)}(h`snd_ump_endpoint_info`h]hsnd_ump_endpoint_info}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjn ubh or }(hjn hhhNhNubj)}(h`snd_ump_block_info`h]hsnd_ump_block_info}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjn ubh data associated with the sequencer client. The USB MIDI driver provides those information from the underlying UMP rawmidi, while a user-space client may provide its own data via }(hjn hhhNhNubj)}(h`*_SET`h]h*_SET}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjn ubh, ioctl. For an Endpoint data, pass 0 to the }(hjn hhhNhNubj)}(h`type`h]htype}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjn ubhA field, while for a Block data, pass the block number + 1 to the }(hjn hhhNhNubj)}(h`type`h]htype}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjn ubhF field. Setting the data for a kernel client shall result in an error.}(hjn hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMuhjj ubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hXhWith UMP 1.1, Function Block information may be changed dynamically. When the update of Function Block is received from the device, ALSA sequencer core changes the corresponding sequencer port name and attributes accordingly, and notifies the changes via the announcement to the ALSA sequencer system port, similarly like the normal port change notification. h]h)}(hXgWith UMP 1.1, Function Block information may be changed dynamically. When the update of Function Block is received from the device, ALSA sequencer core changes the corresponding sequencer port name and attributes accordingly, and notifies the changes via the announcement to the ALSA sequencer system port, similarly like the normal port change notification.h]hXgWith UMP 1.1, Function Block information may be changed dynamically. When the update of Function Block is received from the device, ALSA sequencer core changes the corresponding sequencer port name and attributes accordingly, and notifies the changes via the announcement to the ALSA sequencer system port, similarly like the normal port change notification.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hX]There are two extended event types for notifying the UMP Endpoint and Function Block changes via the system announcement port: type 68 (`SNDRV_SEQ_EVENT_UMP_EP_CHANGE`) and type 69 (`SNDRV_SEQ_EVENT_UMP_BLOCK_CHANGE`). They take the new type, `snd_seq_ev_ump_notify` in the payload, indicating the client number and the FB number that are changed. h]h)}(hX[There are two extended event types for notifying the UMP Endpoint and Function Block changes via the system announcement port: type 68 (`SNDRV_SEQ_EVENT_UMP_EP_CHANGE`) and type 69 (`SNDRV_SEQ_EVENT_UMP_BLOCK_CHANGE`). They take the new type, `snd_seq_ev_ump_notify` in the payload, indicating the client number and the FB number that are changed.h](hThere are two extended event types for notifying the UMP Endpoint and Function Block changes via the system announcement port: type 68 (}(hj hhhNhNubj)}(h`SNDRV_SEQ_EVENT_UMP_EP_CHANGE`h]hSNDRV_SEQ_EVENT_UMP_EP_CHANGE}(hj$ hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh) and type 69 (}(hj hhhNhNubj)}(h"`SNDRV_SEQ_EVENT_UMP_BLOCK_CHANGE`h]h SNDRV_SEQ_EVENT_UMP_BLOCK_CHANGE}(hj6 hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh). They take the new type, }(hj hhhNhNubj)}(h`snd_seq_ev_ump_notify`h]hsnd_seq_ev_ump_notify}(hjH hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubhQ in the payload, indicating the client number and the FB number that are changed.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubeh}(h]h ]h"]h$]h&]jBjuh1hhhhMKhjhhubeh}(h]sequencer-api-extensionsah ]h"]sequencer api extensionsah$]h&]uh1hhhhhhhhMIubh)}(hhh](h)}(h MIDI2 USB Gadget Function Driverh]h MIDI2 USB Gadget Function Driver}(hjw hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjt hhhhhMubh)}(hThe latest kernel contains the support for USB MIDI 2.0 gadget function driver, which can be used for prototyping and debugging MIDI 2.0 features.h]hThe latest kernel contains the support for USB MIDI 2.0 gadget function driver, which can be used for prototyping and debugging MIDI 2.0 features.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjt hhubh)}(h|`CONFIG_USB_GADGET`, `CONFIG_USB_CONFIGFS` and `CONFIG_USB_CONFIGFS_F_MIDI2` need to be enabled for the MIDI2 gadget driver.h](j)}(h`CONFIG_USB_GADGET`h]hCONFIG_USB_GADGET}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh, }(hj hhhNhNubj)}(h`CONFIG_USB_CONFIGFS`h]hCONFIG_USB_CONFIGFS}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh and }(hj hhhNhNubj)}(h`CONFIG_USB_CONFIGFS_F_MIDI2`h]hCONFIG_USB_CONFIGFS_F_MIDI2}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh0 need to be enabled for the MIDI2 gadget driver.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjt hhubh)}(hX@In addition, for using a gadget driver, you need a working UDC driver. In the example below, we use `dummy_hcd` driver (enabled via `CONFIG_USB_DUMMY_HCD`) that is available on PC and VM for debugging purpose. There are other UDC drivers depending on the platform, and those can be used for a real device, instead, too.h](hdIn addition, for using a gadget driver, you need a working UDC driver. In the example below, we use }(hj hhhNhNubj)}(h `dummy_hcd`h]h dummy_hcd}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh driver (enabled via }(hj hhhNhNubj)}(h`CONFIG_USB_DUMMY_HCD`h]hCONFIG_USB_DUMMY_HCD}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh) that is available on PC and VM for debugging purpose. There are other UDC drivers depending on the platform, and those can be used for a real device, instead, too.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjt hhubh)}(hEAt first, on a system to run the gadget, load `libcomposite` module::h](h.At first, on a system to run the gadget, load }(hj hhhNhNubj)}(h`libcomposite`h]h libcomposite}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh module:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjt hhubj=)}(h% modprobe libcompositeh]h% modprobe libcomposite}hj% sbah}(h]h ]h"]h$]h&]jLjMuh1j<hhhMhjt hhubh)}(hand you'll have `usb_gadget` subdirectory under configfs space (typically `/sys/kernel/config` on modern OS). Then create a gadget instance and add configurations there, for example::h](hand you’ll have }(hj3 hhhNhNubj)}(h `usb_gadget`h]h usb_gadget}(hj; hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj3 ubh. subdirectory under configfs space (typically }(hj3 hhhNhNubj)}(h`/sys/kernel/config`h]h/sys/kernel/config}(hjM hhhNhNubah}(h]Rh ]h"]h$]h&]uh1jhj3 ubhY on modern OS). Then create a gadget instance and add configurations there, for example:}(hj3 hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjt hhubj=)}(hX% cd /sys/kernel/config % mkdir usb_gadget/g1 % cd usb_gadget/g1 % mkdir configs/c.1 % mkdir functions/midi2.usb0 % echo 0x0004 > idProduct % echo 0x17b3 > idVendor % mkdir strings/0x409 % echo "ACME Enterprises" > strings/0x409/manufacturer % echo "ACMESynth" > strings/0x409/product % echo "ABCD12345" > strings/0x409/serialnumber % mkdir configs/c.1/strings/0x409 % echo "Monosynth" > configs/c.1/strings/0x409/configuration % echo 120 > configs/c.1/MaxPowerh]hX% cd /sys/kernel/config % mkdir usb_gadget/g1 % cd usb_gadget/g1 % mkdir configs/c.1 % mkdir functions/midi2.usb0 % echo 0x0004 > idProduct % echo 0x17b3 > idVendor % mkdir strings/0x409 % echo "ACME Enterprises" > strings/0x409/manufacturer % echo "ACMESynth" > strings/0x409/product % echo "ABCD12345" > strings/0x409/serialnumber % mkdir configs/c.1/strings/0x409 % echo "Monosynth" > configs/c.1/strings/0x409/configuration % echo 120 > configs/c.1/MaxPower}hje sbah}(h]h ]h"]h$]h&]jLjMuh1j<hhhMhjt hhubh)}(hAt this point, there must be a subdirectory `ep.0`, and that is the configuration for a UMP Endpoint. You can fill the Endpoint information like::h](h,At this point, there must be a subdirectory }(hjs hhhNhNubj)}(h`ep.0`h]hep.0}(hj{ hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjs ubh`, and that is the configuration for a UMP Endpoint. You can fill the Endpoint information like:}(hjs hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjt hhubj=)}(hXy% echo "ACMESynth" > functions/midi2.usb0/iface_name % echo "ACMESynth" > functions/midi2.usb0/ep.0/ep_name % echo "ABCD12345" > functions/midi2.usb0/ep.0/product_id % echo 0x0123 > functions/midi2.usb0/ep.0/family % echo 0x4567 > functions/midi2.usb0/ep.0/model % echo 0x123456 > functions/midi2.usb0/ep.0/manufacturer % echo 0x12345678 > functions/midi2.usb0/ep.0/sw_revisionh]hXy% echo "ACMESynth" > functions/midi2.usb0/iface_name % echo "ACMESynth" > functions/midi2.usb0/ep.0/ep_name % echo "ABCD12345" > functions/midi2.usb0/ep.0/product_id % echo 0x0123 > functions/midi2.usb0/ep.0/family % echo 0x4567 > functions/midi2.usb0/ep.0/model % echo 0x123456 > functions/midi2.usb0/ep.0/manufacturer % echo 0x12345678 > functions/midi2.usb0/ep.0/sw_revision}hj sbah}(h]h ]h"]h$]h&]jLjMuh1j<hhhMhjt hhubh)}(h4The default MIDI protocol can be set either 1 or 2::h]h3The default MIDI protocol can be set either 1 or 2:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjt hhubj=)}(h-% echo 2 > functions/midi2.usb0/ep.0/protocolh]h-% echo 2 > functions/midi2.usb0/ep.0/protocol}hj sbah}(h]h ]h"]h$]h&]jLjMuh1j<hhhMhjt hhubh)}(h{And, you can find a subdirectory `block.0` under this Endpoint subdirectory. This defines the Function Block information::h](h!And, you can find a subdirectory }(hj hhhNhNubj)}(h `block.0`h]hblock.0}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubhP under this Endpoint subdirectory. This defines the Function Block information:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjt hhubj=)}(h% echo "Monosynth" > functions/midi2.usb0/ep.0/block.0/name % echo 0 > functions/midi2.usb0/ep.0/block.0/first_group % echo 1 > functions/midi2.usb0/ep.0/block.0/num_groupsh]h% echo "Monosynth" > functions/midi2.usb0/ep.0/block.0/name % echo 0 > functions/midi2.usb0/ep.0/block.0/first_group % echo 1 > functions/midi2.usb0/ep.0/block.0/num_groups}hj sbah}(h]h ]h"]h$]h&]jLjMuh1j<hhhMhjt hhubh)}(h/Finally, link the configuration and enable it::h]h.Finally, link the configuration and enable it:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjt hhubj=)}(hA% ln -s functions/midi2.usb0 configs/c.1 % echo dummy_udc.0 > UDCh]hA% ln -s functions/midi2.usb0 configs/c.1 % echo dummy_udc.0 > UDC}hj sbah}(h]h ]h"]h$]h&]jLjMuh1j<hhhMhjt hhubh)}(hwhere `dummy_udc.0` is an example case and it differs depending on the system. You can find the UDC instances in `/sys/class/udc` and pass the found name instead::h](hwhere }(hj hhhNhNubj)}(h `dummy_udc.0`h]h dummy_udc.0}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh_ is an example case and it differs depending on the system. You can find the UDC instances in }(hj hhhNhNubj)}(h`/sys/class/udc`h]h/sys/class/udc}(hj! hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh! and pass the found name instead:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjt hhubj=)}(h% ls /sys/class/udc dummy_udc.0h]h% ls /sys/class/udc dummy_udc.0}hj9 sbah}(h]h ]h"]h$]h&]jLjMuh1j<hhhMhjt hhubh)}(hNow, the MIDI 2.0 gadget device is enabled, and the gadget host creates a new sound card instance containing a UMP rawmidi device by `f_midi2` driver::h](hNow, the MIDI 2.0 gadget device is enabled, and the gadget host creates a new sound card instance containing a UMP rawmidi device by }(hjG hhhNhNubj)}(h `f_midi2`h]hf_midi2}(hjO hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjG ubh driver:}(hjG hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjt hhubj=)}(hq% cat /proc/asound/cards .... 1 [Gadget ]: f_midi2 - MIDI 2.0 Gadget MIDI 2.0 Gadgeth]hq% cat /proc/asound/cards .... 1 [Gadget ]: f_midi2 - MIDI 2.0 Gadget MIDI 2.0 Gadget}hjg sbah}(h]h ]h"]h$]h&]jLjMuh1j<hhhMhjt hhubh)}(h~And on the connected host, a similar card should appear, too, but with the card and device names given in the configfs above::h]h}And on the connected host, a similar card should appear, too, but with the card and device names given in the configfs above:}(hju hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjt hhubj=)}(h% cat /proc/asound/cards .... 2 [ACMESynth ]: USB-Audio - ACMESynth ACME Enterprises ACMESynth at usb-dummy_hcd.0-1, high speedh]h% cat /proc/asound/cards .... 2 [ACMESynth ]: USB-Audio - ACMESynth ACME Enterprises ACMESynth at usb-dummy_hcd.0-1, high speed}hj sbah}(h]h ]h"]h$]h&]jLjMuh1j<hhhMhjt hhubh)}(h-You can play a MIDI file on the gadget side::h]h,You can play a MIDI file on the gadget side:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjt hhubj=)}(h% aplaymidi -p 20:1 to_host.midh]h% aplaymidi -p 20:1 to_host.mid}hj sbah}(h]h ]h"]h$]h&]jLjMuh1j<hhhMhjt hhubh)}(hKand this will appear as an input from a MIDI device on the connected host::h]hJand this will appear as an input from a MIDI device on the connected host:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjt hhubj=)}(h% aseqdump -p 20:0 -u 2h]h% aseqdump -p 20:0 -u 2}hj sbah}(h]h ]h"]h$]h&]jLjMuh1j<hhhMhjt hhubh)}(hVVice versa, a playback on the connected host will work as an input on the gadget, too.h]hVVice versa, a playback on the connected host will work as an input on the gadget, too.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjt hhubh)}(hEach Function Block may have different direction and UI-hint, specified via `direction` and `ui_hint` attributes. Passing `1` is for input-only, `2` for out-only and `3` for bidirectional (the default value). For example::h](hLEach Function Block may have different direction and UI-hint, specified via }(hj hhhNhNubj)}(h `direction`h]h direction}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh and }(hj hhhNhNubj)}(h `ui_hint`h]hui_hint}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh attributes. Passing }(hj hhhNhNubj)}(h`1`h]h1}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh is for input-only, }(hj hhhNhNubj)}(h`2`h]h2}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh for out-only and }(hj hhhNhNubj)}(h`3`h]h3}(hj'hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh5 for bidirectional (the default value). For example:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjt hhubj=)}(hk% echo 2 > functions/midi2.usb0/ep.0/block.0/direction % echo 2 > functions/midi2.usb0/ep.0/block.0/ui_hinth]hk% echo 2 > functions/midi2.usb0/ep.0/block.0/direction % echo 2 > functions/midi2.usb0/ep.0/block.0/ui_hint}hj?sbah}(h]h ]h"]h$]h&]jLjMuh1j<hhhMhjt hhubh)}(hWhen you need more than one Function Blocks, you can create subdirectories `block.1`, `block.2`, etc dynamically, and configure them in the configuration procedure above before linking. For example, to create a second Function Block for a keyboard::h](hKWhen you need more than one Function Blocks, you can create subdirectories }(hjMhhhNhNubj)}(h `block.1`h]hblock.1}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjMubh, }(hjMhhhNhNubj)}(h `block.2`h]hblock.2}(hjghhhNhNubah}(h]h ]h"]h$]h&]uh1jhjMubh, etc dynamically, and configure them in the configuration procedure above before linking. For example, to create a second Function Block for a keyboard:}(hjMhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjt hhubj=)}(hXA% mkdir functions/midi2.usb0/ep.0/block.1 % echo "Keyboard" > functions/midi2.usb0/ep.0/block.1/name % echo 1 > functions/midi2.usb0/ep.0/block.1/first_group % echo 1 > functions/midi2.usb0/ep.0/block.1/num_groups % echo 1 > functions/midi2.usb0/ep.0/block.1/direction % echo 1 > functions/midi2.usb0/ep.0/block.1/ui_hinth]hXA% mkdir functions/midi2.usb0/ep.0/block.1 % echo "Keyboard" > functions/midi2.usb0/ep.0/block.1/name % echo 1 > functions/midi2.usb0/ep.0/block.1/first_group % echo 1 > functions/midi2.usb0/ep.0/block.1/num_groups % echo 1 > functions/midi2.usb0/ep.0/block.1/direction % echo 1 > functions/midi2.usb0/ep.0/block.1/ui_hint}hjsbah}(h]h ]h"]h$]h&]jLjMuh1j<hhhMhjt hhubh)}(hhThe `block.*` subdirectories can be removed dynamically, too (except for `block.0` which is persistent).h](hThe }(hjhhhNhNubj)}(h `block.*`h]hblock.*}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh< subdirectories can be removed dynamically, too (except for }(hjhhhNhNubj)}(h `block.0`h]hblock.0}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh which is persistent).}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjt hhubh)}(hFor assigning a Function Block for MIDI 1.0 I/O, set up in `is_midi1` attribute. 1 is for MIDI 1.0, and 2 is for MIDI 1.0 with low speed connection::h](h;For assigning a Function Block for MIDI 1.0 I/O, set up in }(hjhhhNhNubj)}(h `is_midi1`h]his_midi1}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhP attribute. 1 is for MIDI 1.0, and 2 is for MIDI 1.0 with low speed connection:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjt hhubj=)}(h5% echo 2 > functions/midi2.usb0/ep.0/block.1/is_midi1h]h5% echo 2 > functions/midi2.usb0/ep.0/block.1/is_midi1}hjsbah}(h]h ]h"]h$]h&]jLjMuh1j<hhhMhjt hhubh)}(hFor disabling the processing of UMP Stream messages in the gadget driver, pass `0` to `process_ump` attribute in the top-level config::h](hOFor disabling the processing of UMP Stream messages in the gadget driver, pass }(hjhhhNhNubj)}(h`0`h]h0}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh to }(hjhhhNhNubj)}(h `process_ump`h]h process_ump}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh# attribute in the top-level config:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjt hhubj=)}(h+% echo 0 > functions/midi2.usb0/process_umph]h+% echo 0 > functions/midi2.usb0/process_ump}hjsbah}(h]h ]h"]h$]h&]jLjMuh1j<hhhMhjt hhubh)}(hX)The MIDI 1.0 interface at altset 0 is supported by the gadget driver, too. When MIDI 1.0 interface is selected by the connected host, the UMP I/O on the gadget is translated from/to USB MIDI 1.0 packets accordingly while the gadget driver keeps communicating with the user-space over UMP rawmidi.h]hX)The MIDI 1.0 interface at altset 0 is supported by the gadget driver, too. When MIDI 1.0 interface is selected by the connected host, the UMP I/O on the gadget is translated from/to USB MIDI 1.0 packets accordingly while the gadget driver keeps communicating with the user-space over UMP rawmidi.}(hj-hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjt hhubh)}(hOMIDI 1.0 ports are set up from the config in each Function Block. For example::h]hNMIDI 1.0 ports are set up from the config in each Function Block. For example:}(hj;hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM"hjt hhubj=)}(h|% echo 0 > functions/midi2.usb0/ep.0/block.0/midi1_first_group % echo 1 > functions/midi2.usb0/ep.0/block.0/midi1_num_groupsh]h|% echo 0 > functions/midi2.usb0/ep.0/block.0/midi1_first_group % echo 1 > functions/midi2.usb0/ep.0/block.0/midi1_num_groups}hjIsbah}(h]h ]h"]h$]h&]jLjMuh1j<hhhM%hjt hhubh)}(hThe configuration above will enable the Group 1 (the index 0) for MIDI 1.0 interface. Note that those groups must be in the groups defined for the Function Block itself.h]hThe configuration above will enable the Group 1 (the index 0) for MIDI 1.0 interface. Note that those groups must be in the groups defined for the Function Block itself.}(hjWhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM(hjt hhubh)}(hThe gadget driver supports more than one UMP Endpoints, too. Similarly like the Function Blocks, you can create a new subdirectory `ep.1` (but under the card top-level config) to enable a new Endpoint::h](hThe gadget driver supports more than one UMP Endpoints, too. Similarly like the Function Blocks, you can create a new subdirectory }(hjehhhNhNubj)}(h`ep.1`h]hep.1}(hjmhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjeubh@ (but under the card top-level config) to enable a new Endpoint:}(hjehhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM,hjt hhubj=)}(h!% mkdir functions/midi2.usb0/ep.1h]h!% mkdir functions/midi2.usb0/ep.1}hjsbah}(h]h ]h"]h$]h&]jLjMuh1j<hhhM0hjt hhubh)}(huand create a new Function Block there. For example, to create 4 Groups for the Function Block of this new Endpoint::h]htand create a new Function Block there. For example, to create 4 Groups for the Function Block of this new Endpoint:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM2hjt hhubj=)}(ha% mkdir functions/midi2.usb0/ep.1/block.0 % echo 4 > functions/midi2.usb0/ep.1/block.0/num_groupsh]ha% mkdir functions/midi2.usb0/ep.1/block.0 % echo 4 > functions/midi2.usb0/ep.1/block.0/num_groups}hjsbah}(h]h ]h"]h$]h&]jLjMuh1j<hhhM5hjt hhubh)}(hNow, you'll have 4 rawmidi devices in total: the first two are UMP rawmidi devices for Endpoint 0 and Endpoint 1, and other two for the legacy MIDI 1.0 rawmidi devices corresponding to both EP 0 and EP 1.h]hNow, you’ll have 4 rawmidi devices in total: the first two are UMP rawmidi devices for Endpoint 0 and Endpoint 1, and other two for the legacy MIDI 1.0 rawmidi devices corresponding to both EP 0 and EP 1.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM8hjt hhubh)}(hThe current altsetting on the gadget can be informed via a control element "Operation Mode" with `RAWMIDI` iface. e.g. you can read it via `amixer` program running on the gadget host like::h](heThe current altsetting on the gadget can be informed via a control element “Operation Mode” with }(hjhhhNhNubj)}(h `RAWMIDI`h]hRAWMIDI}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh" iface. e.g. you can read it via }(hjhhhNhNubj)}(h`amixer`h]hamixer}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh) program running on the gadget host like:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM<hjt hhubj=)}(h{% amixer -c1 cget iface=RAWMIDI,name='Operation Mode' ; type=INTEGER,access=r--v----,values=1,min=0,max=2,step=0 : values=2h]h{% amixer -c1 cget iface=RAWMIDI,name='Operation Mode' ; type=INTEGER,access=r--v----,values=1,min=0,max=2,step=0 : values=2}hjsbah}(h]h ]h"]h$]h&]jLjMuh1j<hhhM@hjt hhubh)}(hThe value (shown in the second returned line with `: values=`) indicates 1 for MIDI 1.0 (altset 0), 2 for MIDI 2.0 (altset 1) and 0 for unset.h](h2The value (shown in the second returned line with }(hjhhhNhNubj)}(h `: values=`h]h : values=}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhQ) indicates 1 for MIDI 1.0 (altset 0), 2 for MIDI 2.0 (altset 1) and 0 for unset.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMDhjt hhubh)}(h=As of now, the configurations can't be changed after binding.h]h?As of now, the configurations can’t be changed after binding.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMHhjt hhubeh}(h] midi2-usb-gadget-function-driverah ]h"] midi2 usb gadget function driverah$]h&]uh1hhhhhhhhMubeh}(h]midi-2-0-on-linuxah ]h"]midi 2.0 on linuxah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerj^error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourceh _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(j8j5jjjjjjjjjjjjjq jn j0j-u nametypes}(j8jjjjjjjq j0uh}(j5hjhjjjjjjjjjjjn jj-jt u footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages] transformerN include_log] decorationNhhub.