From 8559caa985503d057e55dd7c6362b8f98359ba2e Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Tue, 25 Jul 2023 08:22:04 +0200 Subject: usb: gadget: midi2: Add testing documentation Describing brief testing of the new MIDI 2.0 function driver. Signed-off-by: Takashi Iwai Link: https://lore.kernel.org/r/20230725062206.9674-6-tiwai@suse.de Signed-off-by: Greg Kroah-Hartman --- Documentation/usb/gadget-testing.rst | 141 +++++++++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) (limited to 'Documentation/usb') diff --git a/Documentation/usb/gadget-testing.rst b/Documentation/usb/gadget-testing.rst index 2fca40443dc9..0f3708ae5bc8 100644 --- a/Documentation/usb/gadget-testing.rst +++ b/Documentation/usb/gadget-testing.rst @@ -27,6 +27,7 @@ provided by gadgets. 18. UVC function 19. PRINTER function 20. UAC1 function (new API) + 21. MIDI2 function 1. ACM function @@ -965,3 +966,143 @@ e.g.:: $ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \ aplay -D default:CARD=OdroidU3 + + +21. MIDI2 function +================== + +The function is provided by usb_f_midi2.ko module. +It will create a virtual ALSA card containing a UMP rawmidi device +where the UMP packet is looped back. In addition, a legacy rawmidi +device is created. The UMP rawmidi is bound with ALSA sequencer +clients, too. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "midi2". +The midi2 function provides these attributes in its function directory +as the card top-level information: + + ============= ================================================= + process_ump Bool flag to process UMP Stream messages (0 or 1) + static_block Bool flag for static blocks (0 or 1) + iface_name Optional interface name string + ============= ================================================= + +The directory contains a subdirectory "ep.0", and this provides the +attributes for a UMP Endpoint (which is a pair of USB MIDI Endpoints): + + ============= ================================================= + protocol_caps MIDI protocol capabilities; + 1: MIDI 1.0, 2: MIDI 2.0, or 3: both protocols + protocol Default MIDI protocol (either 1 or 2) + ep_name UMP Endpoint name string + product_id Product ID string + manufacturer Manufacture ID number (24 bit) + family Device family ID number (16 bit) + model Device model ID number (16 bit) + sw_revision Software revision (32 bit) + ============= ================================================= + +Each Endpoint subdirectory contains a subdirectory "block.0", which +represents the Function Block for Block 0 information. +Its attributes are: + + =============== =============================================== + name Function Block name string + direction Direction of this FB + 1: input, 2: output, or 3: bidirectional + first_group The first UMP Group number (0-15) + num_groups The number of groups in this FB (1-16) + ui_hint UI-hint of this FB + 0: unknown, 1: receiver, 2: sender, 3: both + midi_ci_verison Supported MIDI-CI version number (8 bit) + is_midi1 Legacy MIDI 1.0 device (0-2) + 0: MIDI 2.0 device, + 1: MIDI 1.0 without restriction, or + 2: MIDI 1.0 with low speed + sysex8_streams Max number of SysEx8 streams (8 bit) + active Bool flag for FB activity (0 or 1) + =============== =============================================== + +If multiple Function Blocks are required, you can add more Function +Blocks by creating subdirectories "block." with the corresponding +Function Block number (1, 2, ....). The FB subdirectories can be +dynamically removed, too. Note that the Function Block numbers must be +continuous. + +Similarly, if you multiple UMP Endpoints are required, you can add +more Endpoints by creating subdirectories "ep.". The number must +be continuous. + +For emulating the old MIDI 2.0 device without UMP v1.1 support, pass 0 +to `process_ump` flag. Then the whole UMP v1.1 requests are ignored. + +Testing the MIDI2 function +-------------------------- + +On the device: run the gadget, and running:: + + $ cat /proc/asound/cards + +will show a new sound card containing a MIDI2 device. + +OTOH, on the host:: + + $ cat /proc/asound/cards + +will show a new sound card containing either MIDI1 or MIDI2 device, +depending on the USB audio driver configuration. + +On both, when ALSA sequencer is enabled on the host, you can find the +UMP MIDI client such as "MIDI 2.0 Gadget". + +As the driver simply loops back the data, there is no need for a real +device just for testing. + +For testing a MIDI input from the gadget to the host (e.g. emulating a +MIDI keyboard), you can send a MIDI stream like the following. + +On the gadget:: + + $ aconnect -o + .... + client 20: 'MIDI 2.0 Gadget' [type=kernel,card=1] + 0 'MIDI 2.0 ' + 1 'Group 1 (MIDI 2.0 Gadget I/O)' + $ aplaymidi -p 20:1 to_host.mid + +On the host:: + + $ aconnect -i + .... + client 24: 'MIDI 2.0 Gadget' [type=kernel,card=2] + 0 'MIDI 2.0 ' + 1 'Group 1 (MIDI 2.0 Gadget I/O)' + $ arecordmidi -p 24:1 from_gadget.mid + +If you have a UMP-capable application, you can use the UMP port to +send/receive the raw UMP packets, too. For example, aseqdump program +with UMP support can receive from UMP port. On the host:: + + $ aseqdump -u 2 -p 24:1 + Waiting for data. Press Ctrl+C to end. + Source Group Event Ch Data + 24:1 Group 0, Program change 0, program 0, Bank select 0:0 + 24:1 Group 0, Channel pressure 0, value 0x80000000 + +For testing a MIDI output to the gadget to the host (e.g. emulating a +MIDI synth), it'll be just other way round. + +On the gadget:: + + $ arecordmidi -p 20:1 from_host.mid + +On the host:: + + $ aplaymidi -p 24:1 to_gadget.mid + +The access to MIDI 1.0 on altset 0 on the host is supported, and it's +translated from/to UMP packets on the gadget. It's bound to only +Function Block 0. -- cgit v1.2.3 From 1b437d2fb3c1a8c7f2a8a096c0871c8e7c8d109e Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Tue, 25 Jul 2023 08:22:05 +0200 Subject: usb: gadget: midi2: Add "Operation Mode" control Add a new ALSA control element to watch the current operation mode (MIDI 1.0 or MIDI 2.0). It's a read-only control that reflects the current value of altsetting, and 0 means unused, 1 for MIDI 1.0 (altset 0) and 2 for MIDI 2.0 (altset 1). Signed-off-by: Takashi Iwai Link: https://lore.kernel.org/r/20230725062206.9674-7-tiwai@suse.de Signed-off-by: Greg Kroah-Hartman --- Documentation/usb/gadget-testing.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'Documentation/usb') diff --git a/Documentation/usb/gadget-testing.rst b/Documentation/usb/gadget-testing.rst index 0f3708ae5bc8..1fb181d61322 100644 --- a/Documentation/usb/gadget-testing.rst +++ b/Documentation/usb/gadget-testing.rst @@ -1106,3 +1106,14 @@ On the host:: The access to MIDI 1.0 on altset 0 on the host is supported, and it's translated from/to UMP packets on the gadget. It's bound to only Function Block 0. + +The current operation mode can be observed in ALSA control element +"Operation Mode" for SND_CTL_IFACE_RAWMIDI. For example:: + + $ amixer -c1 contents + numid=1,iface=RAWMIDI,name='Operation Mode' + ; type=INTEGER,access=r--v----,values=1,min=0,max=2,step=0 + : values=2 + +where 0 = unused, 1 = MIDI 1.0 (altset 0), 2 = MIDI 2.0 (altset 1). +The example above shows it's running in 2, i.e. MIDI 2.0. -- cgit v1.2.3 From a85ff0db48c372063988f2072a07bd361ce9c4ef Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Tue, 25 Jul 2023 08:22:06 +0200 Subject: usb: gadget: midi2: More flexible MIDI 1.0 configuration This patch allows users to set up MIDI 1.0 ports more flexibly. Namely, instead of the fixed mapping only from FB 0, now multiple block definitions are applied to build up the MIDI 1.0 mapping. The each block config has midi1_first_group and midi1_num_groups attributes, and those specify which Groups are used for MIDI 1.0. Those fields must be within the UMP Groups defined in the block itself. Signed-off-by: Takashi Iwai Link: https://lore.kernel.org/r/20230725062206.9674-8-tiwai@suse.de Signed-off-by: Greg Kroah-Hartman --- Documentation/usb/gadget-testing.rst | 34 ++++++++++++++++++---------------- 1 file changed, 18 insertions(+), 16 deletions(-) (limited to 'Documentation/usb') diff --git a/Documentation/usb/gadget-testing.rst b/Documentation/usb/gadget-testing.rst index 1fb181d61322..394cd226bfae 100644 --- a/Documentation/usb/gadget-testing.rst +++ b/Documentation/usb/gadget-testing.rst @@ -1009,22 +1009,24 @@ Each Endpoint subdirectory contains a subdirectory "block.0", which represents the Function Block for Block 0 information. Its attributes are: - =============== =============================================== - name Function Block name string - direction Direction of this FB - 1: input, 2: output, or 3: bidirectional - first_group The first UMP Group number (0-15) - num_groups The number of groups in this FB (1-16) - ui_hint UI-hint of this FB - 0: unknown, 1: receiver, 2: sender, 3: both - midi_ci_verison Supported MIDI-CI version number (8 bit) - is_midi1 Legacy MIDI 1.0 device (0-2) - 0: MIDI 2.0 device, - 1: MIDI 1.0 without restriction, or - 2: MIDI 1.0 with low speed - sysex8_streams Max number of SysEx8 streams (8 bit) - active Bool flag for FB activity (0 or 1) - =============== =============================================== + ================= =============================================== + name Function Block name string + direction Direction of this FB + 1: input, 2: output, or 3: bidirectional + first_group The first UMP Group number (0-15) + num_groups The number of groups in this FB (1-16) + midi1_first_group The first UMP Group number for MIDI 1.0 (0-15) + midi1_num_groups The number of groups for MIDI 1.0 (0-16) + ui_hint UI-hint of this FB + 0: unknown, 1: receiver, 2: sender, 3: both + midi_ci_verison Supported MIDI-CI version number (8 bit) + is_midi1 Legacy MIDI 1.0 device (0-2) + 0: MIDI 2.0 device, + 1: MIDI 1.0 without restriction, or + 2: MIDI 1.0 with low speed + sysex8_streams Max number of SysEx8 streams (8 bit) + active Bool flag for FB activity (0 or 1) + ================= =============================================== If multiple Function Blocks are required, you can add more Function Blocks by creating subdirectories "block." with the corresponding -- cgit v1.2.3 From f176638af476c6d46257cc3303f5c7cf47d5967d Mon Sep 17 00:00:00 2001 From: Alan Stern Date: Tue, 8 Aug 2023 20:44:35 -0400 Subject: USB: Remove Wireless USB and UWB documentation Support for Wireless USB and Ultra WideBand was removed in 2020 by commit caa6772db4c1 ("Staging: remove wusbcore and UWB from the kernel tree."). But the documentation files were left behind. Let's get rid of that out-of-date documentation. Signed-off-by: Alan Stern Link: https://lore.kernel.org/r/015d4310-bcd3-4ba4-9a0e-3664f281a9be@rowland.harvard.edu Signed-off-by: Greg Kroah-Hartman --- Documentation/usb/authorization.rst | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) (limited to 'Documentation/usb') diff --git a/Documentation/usb/authorization.rst b/Documentation/usb/authorization.rst index 9e53909d04c2..150a14970e95 100644 --- a/Documentation/usb/authorization.rst +++ b/Documentation/usb/authorization.rst @@ -33,12 +33,9 @@ Remove the lock down:: $ echo 1 > /sys/bus/usb/devices/usbX/authorized_default -By default, Wired USB devices are authorized by default to -connect. Wireless USB hosts deauthorize by default all new connected -devices (this is so because we need to do an authentication phase -before authorizing). Writing "2" to the authorized_default attribute -causes kernel to only authorize by default devices connected to internal -USB ports. +By default, all USB devices are authorized. Writing "2" to the +authorized_default attribute causes the kernel to authorize by default +only devices connected to internal USB ports. Example system lockdown (lame) -- cgit v1.2.3