Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux

usb: gadget: midi2: Add testing documentation

Describing brief testing of the new MIDI 2.0 function driver.

Signed-off-by: Takashi Iwai <tiwai@suse.de>
Link: https://lore.kernel.org/r/20230725062206.9674-6-tiwai@suse.de
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

authored by

Takashi Iwai and committed by
Greg Kroah-Hartman
8559caa9 d6468be7

+141
+141
Documentation/usb/gadget-testing.rst
··· 27 27 18. UVC function 28 28 19. PRINTER function 29 29 20. UAC1 function (new API) 30 + 21. MIDI2 function 30 31 31 32 32 33 1. ACM function ··· 966 965 967 966 $ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \ 968 967 aplay -D default:CARD=OdroidU3 968 + 969 + 970 + 21. MIDI2 function 971 + ================== 972 + 973 + The function is provided by usb_f_midi2.ko module. 974 + It will create a virtual ALSA card containing a UMP rawmidi device 975 + where the UMP packet is looped back. In addition, a legacy rawmidi 976 + device is created. The UMP rawmidi is bound with ALSA sequencer 977 + clients, too. 978 + 979 + Function-specific configfs interface 980 + ------------------------------------ 981 + 982 + The function name to use when creating the function directory is "midi2". 983 + The midi2 function provides these attributes in its function directory 984 + as the card top-level information: 985 + 986 + ============= ================================================= 987 + process_ump Bool flag to process UMP Stream messages (0 or 1) 988 + static_block Bool flag for static blocks (0 or 1) 989 + iface_name Optional interface name string 990 + ============= ================================================= 991 + 992 + The directory contains a subdirectory "ep.0", and this provides the 993 + attributes for a UMP Endpoint (which is a pair of USB MIDI Endpoints): 994 + 995 + ============= ================================================= 996 + protocol_caps MIDI protocol capabilities; 997 + 1: MIDI 1.0, 2: MIDI 2.0, or 3: both protocols 998 + protocol Default MIDI protocol (either 1 or 2) 999 + ep_name UMP Endpoint name string 1000 + product_id Product ID string 1001 + manufacturer Manufacture ID number (24 bit) 1002 + family Device family ID number (16 bit) 1003 + model Device model ID number (16 bit) 1004 + sw_revision Software revision (32 bit) 1005 + ============= ================================================= 1006 + 1007 + Each Endpoint subdirectory contains a subdirectory "block.0", which 1008 + represents the Function Block for Block 0 information. 1009 + Its attributes are: 1010 + 1011 + =============== =============================================== 1012 + name Function Block name string 1013 + direction Direction of this FB 1014 + 1: input, 2: output, or 3: bidirectional 1015 + first_group The first UMP Group number (0-15) 1016 + num_groups The number of groups in this FB (1-16) 1017 + ui_hint UI-hint of this FB 1018 + 0: unknown, 1: receiver, 2: sender, 3: both 1019 + midi_ci_verison Supported MIDI-CI version number (8 bit) 1020 + is_midi1 Legacy MIDI 1.0 device (0-2) 1021 + 0: MIDI 2.0 device, 1022 + 1: MIDI 1.0 without restriction, or 1023 + 2: MIDI 1.0 with low speed 1024 + sysex8_streams Max number of SysEx8 streams (8 bit) 1025 + active Bool flag for FB activity (0 or 1) 1026 + =============== =============================================== 1027 + 1028 + If multiple Function Blocks are required, you can add more Function 1029 + Blocks by creating subdirectories "block.<num>" with the corresponding 1030 + Function Block number (1, 2, ....). The FB subdirectories can be 1031 + dynamically removed, too. Note that the Function Block numbers must be 1032 + continuous. 1033 + 1034 + Similarly, if you multiple UMP Endpoints are required, you can add 1035 + more Endpoints by creating subdirectories "ep.<num>". The number must 1036 + be continuous. 1037 + 1038 + For emulating the old MIDI 2.0 device without UMP v1.1 support, pass 0 1039 + to `process_ump` flag. Then the whole UMP v1.1 requests are ignored. 1040 + 1041 + Testing the MIDI2 function 1042 + -------------------------- 1043 + 1044 + On the device: run the gadget, and running:: 1045 + 1046 + $ cat /proc/asound/cards 1047 + 1048 + will show a new sound card containing a MIDI2 device. 1049 + 1050 + OTOH, on the host:: 1051 + 1052 + $ cat /proc/asound/cards 1053 + 1054 + will show a new sound card containing either MIDI1 or MIDI2 device, 1055 + depending on the USB audio driver configuration. 1056 + 1057 + On both, when ALSA sequencer is enabled on the host, you can find the 1058 + UMP MIDI client such as "MIDI 2.0 Gadget". 1059 + 1060 + As the driver simply loops back the data, there is no need for a real 1061 + device just for testing. 1062 + 1063 + For testing a MIDI input from the gadget to the host (e.g. emulating a 1064 + MIDI keyboard), you can send a MIDI stream like the following. 1065 + 1066 + On the gadget:: 1067 + 1068 + $ aconnect -o 1069 + .... 1070 + client 20: 'MIDI 2.0 Gadget' [type=kernel,card=1] 1071 + 0 'MIDI 2.0 ' 1072 + 1 'Group 1 (MIDI 2.0 Gadget I/O)' 1073 + $ aplaymidi -p 20:1 to_host.mid 1074 + 1075 + On the host:: 1076 + 1077 + $ aconnect -i 1078 + .... 1079 + client 24: 'MIDI 2.0 Gadget' [type=kernel,card=2] 1080 + 0 'MIDI 2.0 ' 1081 + 1 'Group 1 (MIDI 2.0 Gadget I/O)' 1082 + $ arecordmidi -p 24:1 from_gadget.mid 1083 + 1084 + If you have a UMP-capable application, you can use the UMP port to 1085 + send/receive the raw UMP packets, too. For example, aseqdump program 1086 + with UMP support can receive from UMP port. On the host:: 1087 + 1088 + $ aseqdump -u 2 -p 24:1 1089 + Waiting for data. Press Ctrl+C to end. 1090 + Source Group Event Ch Data 1091 + 24:1 Group 0, Program change 0, program 0, Bank select 0:0 1092 + 24:1 Group 0, Channel pressure 0, value 0x80000000 1093 + 1094 + For testing a MIDI output to the gadget to the host (e.g. emulating a 1095 + MIDI synth), it'll be just other way round. 1096 + 1097 + On the gadget:: 1098 + 1099 + $ arecordmidi -p 20:1 from_host.mid 1100 + 1101 + On the host:: 1102 + 1103 + $ aplaymidi -p 24:1 to_gadget.mid 1104 + 1105 + The access to MIDI 1.0 on altset 0 on the host is supported, and it's 1106 + translated from/to UMP packets on the gadget. It's bound to only 1107 + Function Block 0.