From patchwork Mon Jun 12 08:10:54 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Takashi Iwai X-Patchwork-Id: 106328 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a59:994d:0:b0:3d9:f83d:47d9 with SMTP id k13csp2440561vqr; Mon, 12 Jun 2023 01:46:24 -0700 (PDT) X-Google-Smtp-Source: ACHHUZ7i9sseHaOQL5myxnC1+vPJVYJmJ+eUSrqgViUHyaebnmMgf3VJYnwgc3W9p8+Qh5yS4g3n X-Received: by 2002:a17:903:41cc:b0:1b3:db5d:e8a0 with SMTP id u12-20020a17090341cc00b001b3db5de8a0mr727052ple.28.1686559584369; Mon, 12 Jun 2023 01:46:24 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1686559584; cv=none; d=google.com; s=arc-20160816; b=qRghQDUjWeIejqHiKe65Iefw0+tDbIdiu4yRcgfKN7hABCwsDgQ/G/tlN/hVJbPEk4 7KrtE/cND+RJ7GVLG/RhWlgiTaF3qPlArm/zQlrJmnWZT469Ajxc8eyBFbrxIeW6bgeT bwfChfpAqKMHYBskxQIMCdHxZ0kM65lhDX3MRg3xC+GprzzU3XSQvPlzrO4cseqafq+A DjaoPFBJ+LNMDX8D/ZSsQOuQ4nxjv4QM5BpqfUw4U9O99jrjLwuZjLxBCIYUs8Gow9R5 D0xX1OemXEKAsxaAVBmpJPhGWfm54bzyfkP28xdaObfXznofisoMtLBSMMIqsNEVRXmI e88A== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from :dkim-signature:dkim-signature; bh=7SIBmxqeQ7gKHxtys0xkr2bAxcRQemUER/BeFZdM6z0=; b=BmzERGcx8Ho+mr0hnufThuvahyYjIwqnGYifq1eN1EeKVABJ92O41A9KkjylYZ66n2 0DzEYwZXipVPtg0CIsMuymM4nkqXXTKR6IilezZg4YbcziYm1Ro288n3t3lRzxTJOgwq w92I4RPKZTuFTh8GSq1VMuSWXLv+3fvsYUOTLYWARMaRlx1E+X2TqTdIo2toOw9FNHN7 FhHgWnq1LzCrM/CBdnJtfyya6cWKspnR7HFs/B+n9yKrAHbxVGgh9cPrVRsLrm8nbBIP XJ1wpC9GKiH4/csykT/0p46Fe/Fj4jdW57An6PbvtMrJ1qe5X3NGPC+RCbwtGPQAwqjj 4LnA== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@suse.de header.s=susede2_rsa header.b=McvdlDx2; dkim=neutral (no key) header.i=@suse.de; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=suse.de Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id h21-20020a170902ac9500b001ab2431f012si2620987plr.423.2023.06.12.01.46.11; Mon, 12 Jun 2023 01:46:24 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@suse.de header.s=susede2_rsa header.b=McvdlDx2; dkim=neutral (no key) header.i=@suse.de; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=suse.de Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231934AbjFLIMn (ORCPT + 99 others); Mon, 12 Jun 2023 04:12:43 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49268 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231932AbjFLIMO (ORCPT ); Mon, 12 Jun 2023 04:12:14 -0400 Received: from smtp-out2.suse.de (smtp-out2.suse.de [IPv6:2001:67c:2178:6::1d]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id D16F21700 for ; Mon, 12 Jun 2023 01:11:46 -0700 (PDT) Received: from imap2.suse-dmz.suse.de (imap2.suse-dmz.suse.de [192.168.254.74]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (P-521) server-digest SHA512) (No client certificate requested) by smtp-out2.suse.de (Postfix) with ESMTPS id 70A332048B; Mon, 12 Jun 2023 08:11:07 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_rsa; t=1686557467; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=7SIBmxqeQ7gKHxtys0xkr2bAxcRQemUER/BeFZdM6z0=; b=McvdlDx2GrstjfjXf8uq08XezKulkiuUGMnUWYBKX2eA1Y8oXJD/+1/4GpwEYKpW+aiyyn cPJxlAgWam5ywxdEmNwmDfRdpxZYYB2p+nsxUDajFoBhCzWT5vzXaA+4IXPRmF08SBrBj9 JzGaiDX3x4S745KvzMjiNsE/OgJlMm4= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_ed25519; t=1686557467; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=7SIBmxqeQ7gKHxtys0xkr2bAxcRQemUER/BeFZdM6z0=; b=MSRPFRgOFIGRDN+kOzpfKdmsoEFKfuUtAb9pNVAJKCZ/SyOXNJx8ux4pKSRey09uW8mFCU nsHcs/c4UM/78nAA== Received: from imap2.suse-dmz.suse.de (imap2.suse-dmz.suse.de [192.168.254.74]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (P-521) server-digest SHA512) (No client certificate requested) by imap2.suse-dmz.suse.de (Postfix) with ESMTPS id 4F8C4138EC; Mon, 12 Jun 2023 08:11:07 +0000 (UTC) Received: from dovecot-director2.suse.de ([192.168.254.65]) by imap2.suse-dmz.suse.de with ESMTPSA id +GlFEhvThmSLcAAAMHmgww (envelope-from ); Mon, 12 Jun 2023 08:11:07 +0000 From: Takashi Iwai To: alsa-devel@alsa-project.org Cc: linux-kernel@vger.kernel.org Subject: [PATCH 10/10] ALSA: docs: Update MIDI 2.0 documentation for UMP 1.1 enhancement Date: Mon, 12 Jun 2023 10:10:54 +0200 Message-Id: <20230612081054.17200-11-tiwai@suse.de> X-Mailer: git-send-email 2.35.3 In-Reply-To: <20230612081054.17200-1-tiwai@suse.de> References: <20230612081054.17200-1-tiwai@suse.de> MIME-Version: 1.0 X-Spam-Status: No, score=-4.4 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_MED,SPF_HELO_NONE, SPF_PASS,T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1768485902696330235?= X-GMAIL-MSGID: =?utf-8?q?1768485902696330235?= There have been a few enhancements for the new UMP 1.1 features. Update the documentation accordingly. Signed-off-by: Takashi Iwai --- Documentation/sound/designs/midi-2.0.rst | 39 ++++++++++++++++++++---- 1 file changed, 33 insertions(+), 6 deletions(-) diff --git a/Documentation/sound/designs/midi-2.0.rst b/Documentation/sound/designs/midi-2.0.rst index d55b0a4c6acb..27d0d3dea1b0 100644 --- a/Documentation/sound/designs/midi-2.0.rst +++ b/Documentation/sound/designs/midi-2.0.rst @@ -68,6 +68,15 @@ 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. +The 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_probe=0` option to +snd-usb-audio driver for skipping the UMP v1.1 inquiries. + When 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 @@ -101,11 +110,15 @@ opening `/dev/snd/midiC*D*` will end up with opening the first substream. Each UMP Endpoint can provide the additional information, constructed -from 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 Group Terminal Block (GTB) in USB -MIDI 2.0 specifications but provide a few more generic information. +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. + The information of UMP Endpoints and UMP Blocks are found in the proc file `/proc/asound/card*/midi*`. For example:: @@ -207,6 +220,8 @@ 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. Note that, although each UMP sequencer client usually creates 16 ports, those ports that don't belong to any UMP Blocks (or belonging @@ -273,6 +288,11 @@ Rawmidi API Extensions The direction is either `SNDRV_UMP_DIR_INPUT`, `SNDRV_UMP_DIR_OUTPUT` or `SNDRV_UMP_DIR_BIDIRECTION`. +* For 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. + Control API Extensions ====================== @@ -337,7 +357,7 @@ Sequencer API Extensions `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 reserved for future use. + The bit 0 is used for filtering UMP groupless messages. * Two new ioctls are added for UMP-capable clients: `SNDRV_SEQ_IOCTL_GET_CLIENT_UMP_INFO` and @@ -349,3 +369,10 @@ Sequencer API Extensions 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. + +* With 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.