From patchwork Thu Jul 29 12:50:41 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Gerd Hoffmann X-Patchwork-Id: 488721 Delivered-To: patch@linaro.org Received: by 2002:a05:6638:1185:0:0:0:0 with SMTP id f5csp2137892jas; Thu, 29 Jul 2021 05:59:18 -0700 (PDT) X-Google-Smtp-Source: ABdhPJxxln1Bu1sXBRCoS/h4a9f9s5GUYywjZCE5HrOs9WehthTRfcm83sHbOR6bBVYRJiFokXUv X-Received: by 2002:a5b:4cc:: with SMTP id u12mr6198948ybp.126.1627563558063; Thu, 29 Jul 2021 05:59:18 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1627563558; cv=none; d=google.com; s=arc-20160816; b=nMAfkBMdJIXYWD4OE9gwBYbKNmYoptbiG5dbj7vDXjlJAQTphmpoiQgjH8XMNPeJon WJABkRNTIcje/qr8P7lc4l8jTgZG08NvaZ3Bxjo5/swW1qNsBdLta40V6VIHfk+CCaGU H+JvTZYp+mvmFtwphKh8s2d9XpO9c/mEmvP0FxEZfXipnatvRp2eai4NHFBJEmqzcjg0 z6eLVLkjNYuuMTOF1y7jtPCl8pgzcz7JgIocq4M2iaMLSEbfedvO314fv/EgIguuKR6p Z++XeVlyUH+fnkAlWE+tvR1RY40Ih8zhdOl8g2oBNum3Od3ouI5Mq4fjwsADaXtCiqut tTKA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:to:from :dkim-signature; bh=PXxVVSgUWJ7PPyaosmTYGPkWrxR46Yjtb32FrGm6NTY=; b=lXPMaIhH9nbOq+ec8jBlwHjQoAqLNcgzWuJ43inDLAhM4PD6B4P+Z7MzE/NfKKXjMg 0sz+zTTrABvjrvg3+pHQZfl0kNdWI8MtUZAymApWR1hcLytWrvrZyAjbTumG3bAaSmXK tMed43QTqZKAOui/cHjZl6pX8+GIoYAeZToSxGCCbV7Ghw9gYXvRIe5631gFS4SK5uMF Y3M6E/gj5EIR/ct0Z5qnXpzR0nMJQlNyozIotQs7XWeeZ31v5DQpZL3z+HKplqW/8Tx2 9Gq2azlTXsV8fwEf48LX7q/NYuwhywui+LOLkEFSSHlQuEz3RjSmQe1tkHJGBFpMW2H7 THUA== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@redhat.com header.s=mimecast20190719 header.b=ePDnwMMB; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id u4si2772778ybk.303.2021.07.29.05.59.17 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Thu, 29 Jul 2021 05:59:18 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=fail header.i=@redhat.com header.s=mimecast20190719 header.b=ePDnwMMB; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=redhat.com Received: from localhost ([::1]:37978 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m95d7-0004Hj-D6 for patch@linaro.org; Thu, 29 Jul 2021 08:59:17 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:40272) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m95VI-00045n-D1 for qemu-devel@nongnu.org; Thu, 29 Jul 2021 08:51:12 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]:26797) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m95VF-0001ez-9w for qemu-devel@nongnu.org; Thu, 29 Jul 2021 08:51:12 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1627563068; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=PXxVVSgUWJ7PPyaosmTYGPkWrxR46Yjtb32FrGm6NTY=; b=ePDnwMMBr+olqwxw/hYjVPQHADIilKI7FtlXbY/K9/GrHZq3nxDVcgIcZ9sUl3DOonqyf5 3/vK4GfnyciNvVTaiB+QCWZKYkDzmBQgcQRgpHvv0gjio4PaFmI/TZEsy1mQol+Rl6QdH6 uWf6/p+LNK+KoqKsSu7CsgUr4QCGYcM= Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-368-fh5xfJZSPbau58bJfvhDGA-1; Thu, 29 Jul 2021 08:51:05 -0400 X-MC-Unique: fh5xfJZSPbau58bJfvhDGA-1 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id AE691190A7A1; Thu, 29 Jul 2021 12:51:04 +0000 (UTC) Received: from sirius.home.kraxel.org (ovpn-114-106.ams2.redhat.com [10.36.114.106]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 376845D6B1; Thu, 29 Jul 2021 12:51:04 +0000 (UTC) Received: by sirius.home.kraxel.org (Postfix, from userid 1000) id B8EEF180093E; Thu, 29 Jul 2021 14:50:44 +0200 (CEST) From: Gerd Hoffmann To: qemu-devel@nongnu.org Subject: [PULL 4/7] docs: Incorporate information in usb-storage.txt into rST manual Date: Thu, 29 Jul 2021 14:50:41 +0200 Message-Id: <20210729125044.3531457-5-kraxel@redhat.com> In-Reply-To: <20210729125044.3531457-1-kraxel@redhat.com> References: <20210729125044.3531457-1-kraxel@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=kraxel@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Received-SPF: pass client-ip=170.10.133.124; envelope-from=kraxel@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -34 X-Spam_score: -3.5 X-Spam_bar: --- X-Spam_report: (-3.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.717, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Peter Maydell , Thomas Huth , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Wainer dos Santos Moschetta , Willian Rampazzo , Gerd Hoffmann , =?utf-8?q?A?= =?utf-8?q?lex_Benn=C3=A9e?= Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell We already have a section on USB in the rST manual; fold the information in docs/usb-storage.txt into it. We add 'format=raw' to the various -drive options in the code examples, because QEMU will print warnings these days if you omit it. Signed-off-by: Peter Maydell Message-Id: <20210728141457.14825-2-peter.maydell@linaro.org> Signed-off-by: Gerd Hoffmann --- docs/usb-storage.txt | 59 ------------------------------------- MAINTAINERS | 2 +- docs/system/devices/usb.rst | 57 ++++++++++++++++++++++++++++++----- 3 files changed, 51 insertions(+), 67 deletions(-) delete mode 100644 docs/usb-storage.txt -- 2.31.1 diff --git a/docs/usb-storage.txt b/docs/usb-storage.txt deleted file mode 100644 index 551af6f88bb1..000000000000 --- a/docs/usb-storage.txt +++ /dev/null @@ -1,59 +0,0 @@ - -qemu usb storage emulation --------------------------- - -QEMU has three devices for usb storage emulation. - -Number one emulates the classic bulk-only transport protocol which is -used by 99% of the usb sticks on the market today and is called -"usb-storage". Usage (hooking up to xhci, other host controllers work -too): - - qemu ${other_vm_args} \ - -drive if=none,id=stick,file=/path/to/file.img \ - -device nec-usb-xhci,id=xhci \ - -device usb-storage,bus=xhci.0,drive=stick - - -Number two is the newer usb attached scsi transport. This one doesn't -automagically create a scsi disk, so you have to explicitly attach one -manually. Multiple logical units are supported. Here is an example -with tree logical units: - - qemu ${other_vm_args} \ - -drive if=none,id=uas-disk1,file=/path/to/file1.img \ - -drive if=none,id=uas-disk2,file=/path/to/file2.img \ - -drive if=none,id=uas-cdrom,media=cdrom,file=/path/to/image.iso \ - -device nec-usb-xhci,id=xhci \ - -device usb-uas,id=uas,bus=xhci.0 \ - -device scsi-hd,bus=uas.0,scsi-id=0,lun=0,drive=uas-disk1 \ - -device scsi-hd,bus=uas.0,scsi-id=0,lun=1,drive=uas-disk2 \ - -device scsi-cd,bus=uas.0,scsi-id=0,lun=5,drive=uas-cdrom - - -Number three emulates the classic bulk-only transport protocol too. -It's called "usb-bot". It shares most code with "usb-storage", and -the guest will not be able to see the difference. The qemu command -line interface is similar to usb-uas though, i.e. no automatic scsi -disk creation. It also features support for up to 16 LUNs. The LUN -numbers must be continuous, i.e. for three devices you must use 0+1+2. -The 0+1+5 numbering from the "usb-uas" example isn't going to work -with "usb-bot". - -Starting with qemu version 2.7 usb-bot and usb-uas devices can be -hotplugged. In the hotplug case they are added with "attached = -false" so the guest will not see the device until the "attached" -property is explicitly set to true. That allows to attach one or more -scsi devices before making the device visible to the guest, i.e. the -workflow looks like this: - - (1) device-add usb-bot,id=foo - (2) device-add scsi-{hd,cd},bus=foo.0,lun=0 - (2b) optionally add more devices (luns 1 ... 15). - (3) scripts/qmp/qom-set foo.attached = true - -enjoy, - Gerd - --- -Gerd Hoffmann diff --git a/MAINTAINERS b/MAINTAINERS index 42ac45c3e502..b1f8e82befc6 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1836,7 +1836,7 @@ S: Maintained F: hw/usb/* F: stubs/usb-dev-stub.c F: tests/qtest/usb-*-test.c -F: docs/usb2.txt +F: docs/system/devices/usb.rst F: docs/usb-storage.txt F: include/hw/usb.h F: include/hw/usb/ diff --git a/docs/system/devices/usb.rst b/docs/system/devices/usb.rst index eeab78dcfbee..7da142ecbb9f 100644 --- a/docs/system/devices/usb.rst +++ b/docs/system/devices/usb.rst @@ -28,17 +28,46 @@ option or the ``device_add`` monitor command. Available devices are: ``usb-storage,drive=drive_id`` Mass storage device backed by drive_id (see the :ref:`disk images` - chapter in the System Emulation Users Guide) + chapter in the System Emulation Users Guide). This is the classic + bulk-only transport protocol used by 99% of USB sticks. This + example shows it connected to an XHCI USB controller and with + a drive backed by a raw format disk image: + + .. parsed-literal:: + + |qemu_system| [...] \\ + -drive if=none,id=stick,format=raw,file=/path/to/file.img \\ + -device nec-usb-xhci,id=xhci \\ + -device usb-storage,bus=xhci.0,drive=stick ``usb-uas`` - USB attached SCSI device, see - `usb-storage.txt `__ - for details + USB attached SCSI device. This does not create a SCSI disk, so + you need to explicitly create a ``scsi-hd`` or ``scsi-cd`` device + on the command line, as well as using the ``-drive`` option to + specify what those disks are backed by. One ``usb-uas`` device can + handle multiple logical units (disks). This example creates three + logical units: two disks and one cdrom drive: + + .. parsed-literal:: + + |qemu_system| [...] \\ + -drive if=none,id=uas-disk1,format=raw,file=/path/to/file1.img \\ + -drive if=none,id=uas-disk2,format=raw,file=/path/to/file2.img \\ + -drive if=none,id=uas-cdrom,media=cdrom,format=raw,file=/path/to/image.iso \\ + -device nec-usb-xhci,id=xhci \\ + -device usb-uas,id=uas,bus=xhci.0 \\ + -device scsi-hd,bus=uas.0,scsi-id=0,lun=0,drive=uas-disk1 \\ + -device scsi-hd,bus=uas.0,scsi-id=0,lun=1,drive=uas-disk2 \\ + -device scsi-cd,bus=uas.0,scsi-id=0,lun=5,drive=uas-cdrom ``usb-bot`` - Bulk-only transport storage device, see - `usb-storage.txt `__ - for details here, too + Bulk-only transport storage device. This presents the guest with the + same USB bulk-only transport protocol interface as ``usb-storage``, but + the QEMU command line option works like ``usb-uas`` and does not + automatically create SCSI disks for you. ``usb-bot`` supports up to + 16 LUNs. Unlike ``usb-uas``, the LUN numbers must be continuous, + i.e. for three devices you must use 0+1+2. The 0+1+5 numbering from the + ``usb-uas`` example above won't work with ``usb-bot``. ``usb-mtp,rootdir=dir`` Media transfer protocol device, using dir as root of the file tree @@ -84,6 +113,20 @@ option or the ``device_add`` monitor command. Available devices are: ``u2f-{emulated,passthru}`` Universal Second Factor device +Hotplugging USB storage +~~~~~~~~~~~~~~~~~~~~~~~ + +The ``usb-bot`` and ``usb-uas`` devices can be hotplugged. In the hotplug +case they are added with ``attached = false`` so the guest will not see +the device until the ``attached`` property is explicitly set to true. +That allows you to attach one or more scsi devices before making the +device visible to the guest. The workflow looks like this: + +#. ``device-add usb-bot,id=foo`` +#. ``device-add scsi-{hd,cd},bus=foo.0,lun=0`` +#. optionally add more devices (luns 1 ... 15) +#. ``scripts/qmp/qom-set foo.attached = true`` + .. _host_005fusb_005fdevices: Using host USB devices on a Linux host From patchwork Thu Jul 29 12:50:42 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Gerd Hoffmann X-Patchwork-Id: 488720 Delivered-To: patch@linaro.org Received: by 2002:a05:6638:1185:0:0:0:0 with SMTP id f5csp2136182jas; Thu, 29 Jul 2021 05:56:22 -0700 (PDT) X-Google-Smtp-Source: ABdhPJwhFC7E0RQO+d3FZVu6+ZmhuMk01KMgGIxY2AEIvHtHuil/FVtoblT/3DJJHMWR43OHORI4 X-Received: by 2002:a25:6088:: with SMTP id u130mr6645793ybb.257.1627563382328; Thu, 29 Jul 2021 05:56:22 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1627563382; cv=none; d=google.com; s=arc-20160816; b=Fzw+qRKqKF9XdPREgnblq056tWBSXCsvlMt+DpIgHvyzmmqiRRHZl/nRz8TzIad0b0 m+gAOtEnpN5JatEnkXRP3ChLrxI0oHoXwigKtC6EmfT02NWzgq0Gw2Tr+KQjW91q8ulq 1IO/NFxtRwWsU71PLBBNBEx5f7iFEufEofxC1lLdfLY2QOUIdC3LF5Ay3PT4mWVctBUV sjjCPgn+SLzwAXgdIU4J17w3mGsebV0Ypt1fXTmFLixhndRNLa93Jh4k8Y7NRxzvaMd4 kQD5MovR0vCQ+i9Y+yqtsGDUFv7Lve9QFRSO4NlVrDybStzd6k6MK3u80KQF+PmqaqL0 Z0YQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:to:from :dkim-signature; bh=pR356JI7WfZBxcmNd8NhVPrZBjuiWMKSv46FRRJidCU=; b=yB2vDt43Iyj/USR9xgNKJJ33Zs24seKod43FUQX2CEsYf6oE3HZSx/oPluNhF68N0J bs+KH0x5jrv2aRUtbkhctZyor/pZIExbxP9F8Zg7vpZWvZ7eSNtlWPY4Hjc8zDU+kaIg eni903SY85BFDWeJaGCQCzx2qdWJjnL59KVbqi27jYHc4h1bb/lNnv2mRD+ZKeMjiiiD vLhVzVIIbWsiGFh8XvLMDzLeUnw09ibkb+x/3a+rvANOTm53ZMl2cTZEAvneavOa+AVK xQSvEpsUWaPxu7K3HIePEAnYDiapGdbs1T8mb995CKhwv3ZiYGFFHZRlucCmQmyMMfaE tSow== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@redhat.com header.s=mimecast20190719 header.b=BxgD4EjT; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id s129si3036707ybc.232.2021.07.29.05.56.22 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Thu, 29 Jul 2021 05:56:22 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=fail header.i=@redhat.com header.s=mimecast20190719 header.b=BxgD4EjT; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=redhat.com Received: from localhost ([::1]:58712 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m95aH-0007UV-NF for patch@linaro.org; Thu, 29 Jul 2021 08:56:21 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:40370) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m95VQ-0004b7-6V for qemu-devel@nongnu.org; Thu, 29 Jul 2021 08:51:20 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]:38263) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m95VN-0001p6-W0 for qemu-devel@nongnu.org; Thu, 29 Jul 2021 08:51:19 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1627563077; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=pR356JI7WfZBxcmNd8NhVPrZBjuiWMKSv46FRRJidCU=; b=BxgD4EjTgZBZ5f8WFAHmf21ENIvWtQzVsQYv3i5KEcQgue2d5bePSMjWq5S1JXZeecfAXI Rar6HsFYwZ/HYA2zJGcUlKsSW0KdqYJ3hfHm1hWHp1R2pYsGr/wnvDxjF61RRiUfz2hZje tw+GYFWADNh/uL9/8/eiWhJ5G5ZeZ+c= Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-566-WSSg6QieP8O33VpAzUtJTw-1; Thu, 29 Jul 2021 08:51:15 -0400 X-MC-Unique: WSSg6QieP8O33VpAzUtJTw-1 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id A80401006C83; Thu, 29 Jul 2021 12:51:14 +0000 (UTC) Received: from sirius.home.kraxel.org (ovpn-114-106.ams2.redhat.com [10.36.114.106]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 2603719811; Thu, 29 Jul 2021 12:51:06 +0000 (UTC) Received: by sirius.home.kraxel.org (Postfix, from userid 1000) id C62881800980; Thu, 29 Jul 2021 14:50:44 +0200 (CEST) From: Gerd Hoffmann To: qemu-devel@nongnu.org Subject: [PULL 5/7] docs: Fold usb2.txt USB controller information into usb.rst Date: Thu, 29 Jul 2021 14:50:42 +0200 Message-Id: <20210729125044.3531457-6-kraxel@redhat.com> In-Reply-To: <20210729125044.3531457-1-kraxel@redhat.com> References: <20210729125044.3531457-1-kraxel@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=kraxel@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Received-SPF: pass client-ip=170.10.133.124; envelope-from=kraxel@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -34 X-Spam_score: -3.5 X-Spam_bar: --- X-Spam_report: (-3.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.717, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Peter Maydell , Thomas Huth , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Wainer dos Santos Moschetta , Willian Rampazzo , Gerd Hoffmann , =?utf-8?q?A?= =?utf-8?q?lex_Benn=C3=A9e?= Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell Fold the information in docs/usb2.txt about the different kinds of supported USB controller into the main rST manual. Signed-off-by: Peter Maydell Message-Id: <20210728141457.14825-3-peter.maydell@linaro.org> Signed-off-by: Gerd Hoffmann --- docs/usb2.txt | 82 ----------------------------------- docs/system/devices/usb.rst | 86 +++++++++++++++++++++++++++++++++++++ 2 files changed, 86 insertions(+), 82 deletions(-) -- 2.31.1 diff --git a/docs/usb2.txt b/docs/usb2.txt index 172614d3a7e0..adf4ba3f2a0c 100644 --- a/docs/usb2.txt +++ b/docs/usb2.txt @@ -1,86 +1,4 @@ -USB Quick Start -=============== - -XHCI controller support ------------------------ - -QEMU has XHCI host adapter support. The XHCI hardware design is much -more virtualization-friendly when compared to EHCI and UHCI, thus XHCI -emulation uses less resources (especially cpu). So if your guest -supports XHCI (which should be the case for any operating system -released around 2010 or later) we recommend using it: - - qemu -device qemu-xhci - -XHCI supports USB 1.1, USB 2.0 and USB 3.0 devices, so this is the -only controller you need. With only a single USB controller (and -therefore only a single USB bus) present in the system there is no -need to use the bus= parameter when adding USB devices. - - -EHCI controller support ------------------------ - -The QEMU EHCI Adapter supports USB 2.0 devices. It can be used either -standalone or with companion controllers (UHCI, OHCI) for USB 1.1 -devices. The companion controller setup is more convenient to use -because it provides a single USB bus supporting both USB 2.0 and USB -1.1 devices. See next section for details. - -When running EHCI in standalone mode you can add UHCI or OHCI -controllers for USB 1.1 devices too. Each controller creates its own -bus though, so there are two completely separate USB buses: One USB -1.1 bus driven by the UHCI controller and one USB 2.0 bus driven by -the EHCI controller. Devices must be attached to the correct -controller manually. - -The easiest way to add a UHCI controller to a 'pc' machine is the -'-usb' switch. QEMU will create the UHCI controller as function of -the PIIX3 chipset. The USB 1.1 bus will carry the name "usb-bus.0". - -You can use the standard -device switch to add a EHCI controller to -your virtual machine. It is strongly recommended to specify an ID for -the controller so the USB 2.0 bus gets an individual name, for example -'-device usb-ehci,id=ehci". This will give you a USB 2.0 bus named -"ehci.0". - -When adding USB devices using the -device switch you can specify the -bus they should be attached to. Here is a complete example: - - qemu -M pc ${otheroptions} \ - -drive if=none,id=usbstick,file=/path/to/image \ - -usb \ - -device usb-ehci,id=ehci \ - -device usb-tablet,bus=usb-bus.0 \ - -device usb-storage,bus=ehci.0,drive=usbstick - -This attaches a USB tablet to the UHCI adapter and a USB mass storage -device to the EHCI adapter. - - -Companion controller support ----------------------------- - -The UHCI and OHCI controllers can attach to a USB bus created by EHCI -as companion controllers. This is done by specifying the masterbus -and firstport properties. masterbus specifies the bus name the -controller should attach to. firstport specifies the first port the -controller should attach to, which is needed as usually one EHCI -controller with six ports has three UHCI companion controllers with -two ports each. - -There is a config file in docs which will do all this for -you, just try ... - - qemu -readconfig docs/config/ich9-ehci-uhci.cfg - -... then use "bus=ehci.0" to assign your USB devices to that bus. - -Using the '-usb' switch for 'q35' machines will create a similar -USB controller configuration. - - More USB tips & tricks ====================== diff --git a/docs/system/devices/usb.rst b/docs/system/devices/usb.rst index 7da142ecbb9f..9f0e613dcc7c 100644 --- a/docs/system/devices/usb.rst +++ b/docs/system/devices/usb.rst @@ -8,6 +8,92 @@ plug virtual USB devices or real host USB devices (only works with certain host operating systems). QEMU will automatically create and connect virtual USB hubs as necessary to connect multiple USB devices. +USB controllers +~~~~~~~~~~~~~~~ + +XHCI controller support +^^^^^^^^^^^^^^^^^^^^^^^ + +QEMU has XHCI host adapter support. The XHCI hardware design is much +more virtualization-friendly when compared to EHCI and UHCI, thus XHCI +emulation uses less resources (especially CPU). So if your guest +supports XHCI (which should be the case for any operating system +released around 2010 or later) we recommend using it: + + qemu -device qemu-xhci + +XHCI supports USB 1.1, USB 2.0 and USB 3.0 devices, so this is the +only controller you need. With only a single USB controller (and +therefore only a single USB bus) present in the system there is no +need to use the bus= parameter when adding USB devices. + + +EHCI controller support +^^^^^^^^^^^^^^^^^^^^^^^ + +The QEMU EHCI Adapter supports USB 2.0 devices. It can be used either +standalone or with companion controllers (UHCI, OHCI) for USB 1.1 +devices. The companion controller setup is more convenient to use +because it provides a single USB bus supporting both USB 2.0 and USB +1.1 devices. See next section for details. + +When running EHCI in standalone mode you can add UHCI or OHCI +controllers for USB 1.1 devices too. Each controller creates its own +bus though, so there are two completely separate USB buses: One USB +1.1 bus driven by the UHCI controller and one USB 2.0 bus driven by +the EHCI controller. Devices must be attached to the correct +controller manually. + +The easiest way to add a UHCI controller to a ``pc`` machine is the +``-usb`` switch. QEMU will create the UHCI controller as function of +the PIIX3 chipset. The USB 1.1 bus will carry the name ``usb-bus.0``. + +You can use the standard ``-device`` switch to add a EHCI controller to +your virtual machine. It is strongly recommended to specify an ID for +the controller so the USB 2.0 bus gets an individual name, for example +``-device usb-ehci,id=ehci``. This will give you a USB 2.0 bus named +``ehci.0``. + +When adding USB devices using the ``-device`` switch you can specify the +bus they should be attached to. Here is a complete example: + +.. parsed-literal:: + + |qemu_system| -M pc ${otheroptions} \\ + -drive if=none,id=usbstick,format=raw,file=/path/to/image \\ + -usb \\ + -device usb-ehci,id=ehci \\ + -device usb-tablet,bus=usb-bus.0 \\ + -device usb-storage,bus=ehci.0,drive=usbstick + +This attaches a USB tablet to the UHCI adapter and a USB mass storage +device to the EHCI adapter. + + +Companion controller support +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The UHCI and OHCI controllers can attach to a USB bus created by EHCI +as companion controllers. This is done by specifying the ``masterbus`` +and ``firstport`` properties. ``masterbus`` specifies the bus name the +controller should attach to. ``firstport`` specifies the first port the +controller should attach to, which is needed as usually one EHCI +controller with six ports has three UHCI companion controllers with +two ports each. + +There is a config file in docs which will do all this for +you, which you can use like this: + +.. parsed-literal:: + + |qemu_system| -readconfig docs/config/ich9-ehci-uhci.cfg + +Then use ``bus=ehci.0`` to assign your USB devices to that bus. + +Using the ``-usb`` switch for ``q35`` machines will create a similar +USB controller configuration. + + .. _Connecting USB devices: Connecting USB devices From patchwork Thu Jul 29 12:50:43 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Gerd Hoffmann X-Patchwork-Id: 488719 Delivered-To: patch@linaro.org Received: by 2002:a05:6638:1185:0:0:0:0 with SMTP id f5csp2134050jas; Thu, 29 Jul 2021 05:53:24 -0700 (PDT) X-Google-Smtp-Source: ABdhPJyn0wlu3nByiP+q+zjqOOuHDL+3xwq/uzOZ3LnrKUdjUwbLmGRn2AmP5VlDgHKSJaEyqO5T X-Received: by 2002:ab0:209:: with SMTP id 9mr3998041uas.135.1627563204194; Thu, 29 Jul 2021 05:53:24 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1627563204; cv=none; d=google.com; s=arc-20160816; b=Li1WxDyK6eXSdi2oy4c/5ScvMWd4Tcc4e6oIx2z04idMAo4eMOHrFmFYH/vhpIJVL1 LlVjJdqmJpBr/DIkaMFeuvwg2ilk1vc1yME7L4Wb8CPeWydd88aL+fCrA3Mq2RW27XIY tDAVYosf8bwJqu8pnxZfXLb+5y84YIWBioYfIW7y84LEKeE8yVK1qa8R7oI66vlR3zpe kFKqr/TFmJZjoBdA0w3brcOiwEveuhitHnu8S4Igawv9sgpy07cKonWflQkKl/fLQUNJ NZpyqiT6B874cdl1KfBur3vIwh+tV2FUhpHow/bXp9Qkw+79Ua9Swd3o419sXKEodsms mdWw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:to:from :dkim-signature; bh=P2G7uEUlC1wBa+DO0orPvkKIN2JlSfV8MvgpAs3qKe0=; b=UKZdK1SoesN5iRTb9f1yYWLCyvPyEAAl2VDVy/4pK59RFmeqQM5lUbWp+/lEO+Jwce M0uj6wkpO1+OOD7QLqgSk+9RkJU3F5cLHOsJgEveKlmQ3KUkha8AWc1pU7yJZEsCWVCr PtkDSgHF4lIOf+iu5j+Suo9qQrukZKfY8XPFXlN1RJE+MBSjxYMKkCJPuz+2DacOa56p 6cpqUxzChVSZeJJAVU6AimaFzTW+jLVReOcutJX3yZkTeLcy3vJaxqZzLtBqNeuCARmz KHv5ffQSD4uU2JItnT3qrOJeSTMox+JmUF/+kL6E933YLEx9gwZG+ceq4MCtMELu3zSL AXoQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@redhat.com header.s=mimecast20190719 header.b=SKd9kiR3; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id o5si1371605uae.91.2021.07.29.05.53.24 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Thu, 29 Jul 2021 05:53:24 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=fail header.i=@redhat.com header.s=mimecast20190719 header.b=SKd9kiR3; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=redhat.com Received: from localhost ([::1]:46046 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m95XP-000795-H0 for patch@linaro.org; Thu, 29 Jul 2021 08:53:23 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:40424) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m95VZ-00053g-4z for qemu-devel@nongnu.org; Thu, 29 Jul 2021 08:51:29 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:25090) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m95VX-0001v2-B9 for qemu-devel@nongnu.org; Thu, 29 Jul 2021 08:51:28 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1627563086; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=P2G7uEUlC1wBa+DO0orPvkKIN2JlSfV8MvgpAs3qKe0=; b=SKd9kiR3nxMgJbCvtccUVaHs1WQLAoArzixN3dCJqfKL+16/sDlo3LybOMqW9eQDronIBF IQx8BjgQ4/PLE6AL4FJ7eatXFpslKNCu71IYge/n4Ojdk4NpBh3B7jr8mxsmEPFbarxzLc 7D9nH3FH2IUcRBnogwtsFzXVpdGpijE= Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-331-JLKiq9QLOJyyupNXBnroFw-1; Thu, 29 Jul 2021 08:51:23 -0400 X-MC-Unique: JLKiq9QLOJyyupNXBnroFw-1 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 6398E107ACF5; Thu, 29 Jul 2021 12:51:22 +0000 (UTC) Received: from sirius.home.kraxel.org (ovpn-114-106.ams2.redhat.com [10.36.114.106]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 6B56D5C1D1; Thu, 29 Jul 2021 12:51:12 +0000 (UTC) Received: by sirius.home.kraxel.org (Postfix, from userid 1000) id D2B661800981; Thu, 29 Jul 2021 14:50:44 +0200 (CEST) From: Gerd Hoffmann To: qemu-devel@nongnu.org Subject: [PULL 6/7] docs: Fold usb2.txt physical port addressing info into usb.rst Date: Thu, 29 Jul 2021 14:50:43 +0200 Message-Id: <20210729125044.3531457-7-kraxel@redhat.com> In-Reply-To: <20210729125044.3531457-1-kraxel@redhat.com> References: <20210729125044.3531457-1-kraxel@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=kraxel@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Received-SPF: pass client-ip=216.205.24.124; envelope-from=kraxel@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -34 X-Spam_score: -3.5 X-Spam_bar: --- X-Spam_report: (-3.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.717, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Peter Maydell , Thomas Huth , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Wainer dos Santos Moschetta , Willian Rampazzo , Gerd Hoffmann , =?utf-8?q?A?= =?utf-8?q?lex_Benn=C3=A9e?= Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell Fold the usb2.txt documentation about specifying which physical port a USB device should use into usb.rst. Signed-off-by: Peter Maydell Message-Id: <20210728141457.14825-4-peter.maydell@linaro.org> Signed-off-by: Gerd Hoffmann --- docs/usb2.txt | 32 -------------------------------- docs/system/devices/usb.rst | 33 +++++++++++++++++++++++++++++++++ 2 files changed, 33 insertions(+), 32 deletions(-) -- 2.31.1 diff --git a/docs/usb2.txt b/docs/usb2.txt index adf4ba3f2a0c..6a88d5314f9c 100644 --- a/docs/usb2.txt +++ b/docs/usb2.txt @@ -6,38 +6,6 @@ Recently the USB pass through driver (also known as usb-host) and the QEMU USB subsystem gained a few capabilities which are available only via qdev properties, i,e. when using '-device'. - -physical port addressing ------------------------- - -First you can (for all USB devices) specify the physical port where -the device will show up in the guest. This can be done using the -"port" property. UHCI has two root ports (1,2). EHCI has six root -ports (1-6), the emulated (1.1) USB hub has eight ports. - -Plugging a tablet into UHCI port 1 works like this: - - -device usb-tablet,bus=usb-bus.0,port=1 - -Plugging a hub into UHCI port 2 works like this: - - -device usb-hub,bus=usb-bus.0,port=2 - -Plugging a virtual USB stick into port 4 of the hub just plugged works -this way: - - -device usb-storage,bus=usb-bus.0,port=2.4,drive=... - -You can do basically the same in the monitor using the device_add -command. If you want to unplug devices too you should specify some -unique id which you can use to refer to the device ... - - (qemu) device_add usb-tablet,bus=usb-bus.0,port=1,id=my-tablet - (qemu) device_del my-tablet - -... when unplugging it with device_del. - - USB pass through hints ---------------------- diff --git a/docs/system/devices/usb.rst b/docs/system/devices/usb.rst index 9f0e613dcc7c..bab0cd3fdfd1 100644 --- a/docs/system/devices/usb.rst +++ b/docs/system/devices/usb.rst @@ -199,6 +199,39 @@ option or the ``device_add`` monitor command. Available devices are: ``u2f-{emulated,passthru}`` Universal Second Factor device +Physical port addressing +^^^^^^^^^^^^^^^^^^^^^^^^ + +For all the above USB devices, by default QEMU will plug the device +into the next available port on the specified USB bus, or onto +some available USB bus if you didn't specify one explicitly. +If you need to, you can also specify the physical port where +the device will show up in the guest. This can be done using the +``port`` property. UHCI has two root ports (1,2). EHCI has six root +ports (1-6), and the emulated (1.1) USB hub has eight ports. + +Plugging a tablet into UHCI port 1 works like this:: + + -device usb-tablet,bus=usb-bus.0,port=1 + +Plugging a hub into UHCI port 2 works like this:: + + -device usb-hub,bus=usb-bus.0,port=2 + +Plugging a virtual USB stick into port 4 of the hub just plugged works +this way:: + + -device usb-storage,bus=usb-bus.0,port=2.4,drive=... + +In the monitor, the ``device_add` command also accepts a ``port`` +property specification. If you want to unplug devices too you should +specify some unique id which you can use to refer to the device. +You can then use ``device_del`` to unplug the device later. +For example:: + + (qemu) device_add usb-tablet,bus=usb-bus.0,port=1,id=my-tablet + (qemu) device_del my-tablet + Hotplugging USB storage ~~~~~~~~~~~~~~~~~~~~~~~ From patchwork Thu Jul 29 12:50:44 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Gerd Hoffmann X-Patchwork-Id: 488722 Delivered-To: patch@linaro.org Received: by 2002:a05:6638:1185:0:0:0:0 with SMTP id f5csp2141583jas; Thu, 29 Jul 2021 06:03:12 -0700 (PDT) X-Google-Smtp-Source: ABdhPJxEjPfndVrLZZJagdypkUjgfte3sOPfFHwnXMrAK4L/ZlKKwnnMqV+x6EmGThYVuoacOc0T X-Received: by 2002:a7b:c3d3:: with SMTP id t19mr4512515wmj.156.1627563792025; Thu, 29 Jul 2021 06:03:12 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1627563792; cv=none; d=google.com; s=arc-20160816; b=OqRtO6HeIXf43d6V/pscX+k5Wyh3c51zypbertsWTd+bcQBIZgDFJ0gnjZKfNo9hAp OA6E+j75H5lkIc9R8nzh6sgZzG71kIB1+KeqwPo+cD/ZKlC02D4KM03KYl1MS8ernom4 pssewUxxVlBaPVUNBfDVNpnwz1mLtpDVJcFJO1lxRCHENjgC+7BMTDWCuyOaWr/HyOq0 Odd/ERLt7H8AG7qcHHM80QhcKfVY8J4tldIG+TyHy/TjfxFGWOGLXazuaKLm8D29rGwv e7ZBS0+pFC44utrhbszxt3zSws0FrFpta7GfVhxiQPN1EO28AeNQp9nQMXsqr1qAlNzd Ko9A== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:to:from :dkim-signature; bh=wMludD6UGs3ht2eHfU0N4k6LyN19995Gi/P5zkCnfoA=; b=DGuRG+Luz0Gmh2Y7ked8CF83dA8k+CZvFKv/8BA2ed78WimWpUQGqoCTwW/EF29RXM BeagR3jBoLxZ7dqIhKfpjcXEgpgDwLrpfXYF85JrcgXlPUh+lLuhBdjKhc3ScdPlHnT1 BqH/5uuWzxeKv6DGJ3/9lK8u85v0frAZdGyBMHOqZeEvt/BELmVS9tiDJGEfi2wr3lst 0wRiMGLoT7ReeqBUVeyZ/c3u9lmk/0s7HtDuaWGWjU8b9fmbk9MVHIlozbLb7scKxWZr SJrWCNTietgfGK7h2ahrlib8lU9nG2Rmt2UXPq+7OnswcZUyYlNXRR0V1oj5n33hU2GI IblQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@redhat.com header.s=mimecast20190719 header.b=S4X6nJjk; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id h9si2737253wro.381.2021.07.29.06.03.11 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Thu, 29 Jul 2021 06:03:12 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=fail header.i=@redhat.com header.s=mimecast20190719 header.b=S4X6nJjk; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=redhat.com Received: from localhost ([::1]:43356 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m95gt-0008Cd-0M for patch@linaro.org; Thu, 29 Jul 2021 09:03:11 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:40436) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m95Vb-00059G-6T for qemu-devel@nongnu.org; Thu, 29 Jul 2021 08:51:32 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:42900) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m95VZ-0001xZ-D3 for qemu-devel@nongnu.org; Thu, 29 Jul 2021 08:51:30 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1627563088; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=wMludD6UGs3ht2eHfU0N4k6LyN19995Gi/P5zkCnfoA=; b=S4X6nJjkcgEQ2i4RPvZi/R4CjYLg2idM8wZfAS1/Sm+7L9hCUcOtLVrdIO5A5KnoqKvBeV fkQxQYqi54PBSSoszfRRoMhzBk3jiTCah4QQF0ss/lEYk+ejyp545WQ9a+WysLoNGbzrmJ 69EPKG7qswKd171rgO+SI1IbONUw3R0= Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-453-X5f9QunaOBmyvRxl_m1r-w-1; Thu, 29 Jul 2021 08:51:27 -0400 X-MC-Unique: X5f9QunaOBmyvRxl_m1r-w-1 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 53AE492505; Thu, 29 Jul 2021 12:51:26 +0000 (UTC) Received: from sirius.home.kraxel.org (ovpn-114-106.ams2.redhat.com [10.36.114.106]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 00CA126E5E; Thu, 29 Jul 2021 12:51:15 +0000 (UTC) Received: by sirius.home.kraxel.org (Postfix, from userid 1000) id E1DAF1800982; Thu, 29 Jul 2021 14:50:44 +0200 (CEST) From: Gerd Hoffmann To: qemu-devel@nongnu.org Subject: [PULL 7/7] docs: Fold usb2.txt passthrough information into usb.rst Date: Thu, 29 Jul 2021 14:50:44 +0200 Message-Id: <20210729125044.3531457-8-kraxel@redhat.com> In-Reply-To: <20210729125044.3531457-1-kraxel@redhat.com> References: <20210729125044.3531457-1-kraxel@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=kraxel@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Received-SPF: pass client-ip=216.205.24.124; envelope-from=kraxel@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -34 X-Spam_score: -3.5 X-Spam_bar: --- X-Spam_report: (-3.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.717, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Peter Maydell , Thomas Huth , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Wainer dos Santos Moschetta , Willian Rampazzo , Gerd Hoffmann , =?utf-8?q?A?= =?utf-8?q?lex_Benn=C3=A9e?= Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell Fold the usb2.txt information on device passthrough into usb.rst; since this is the last part of the .txt file we can delete it now. Signed-off-by: Peter Maydell Message-Id: <20210728141457.14825-5-peter.maydell@linaro.org> Signed-off-by: Gerd Hoffmann --- docs/usb2.txt | 58 ------------------------------------- MAINTAINERS | 1 - docs/system/devices/usb.rst | 49 +++++++++++++++++++++++++++++++ 3 files changed, 49 insertions(+), 59 deletions(-) delete mode 100644 docs/usb2.txt -- 2.31.1 diff --git a/docs/usb2.txt b/docs/usb2.txt deleted file mode 100644 index 6a88d5314f9c..000000000000 --- a/docs/usb2.txt +++ /dev/null @@ -1,58 +0,0 @@ - -More USB tips & tricks -====================== - -Recently the USB pass through driver (also known as usb-host) and the -QEMU USB subsystem gained a few capabilities which are available only -via qdev properties, i,e. when using '-device'. - -USB pass through hints ----------------------- - -The usb-host driver has a bunch of properties to specify the device -which should be passed to the guest: - - hostbus= -- Specifies the bus number the device must be attached - to. - - hostaddr= -- Specifies the device address the device got - assigned by the guest os. - - hostport= -- Specifies the physical port the device is attached - to. - - vendorid= -- Specifies the vendor ID of the device. - productid= -- Specifies the product ID of the device. - -In theory you can combine all these properties as you like. In -practice only a few combinations are useful: - - (1) vendorid+productid -- match for a specific device, pass it to - the guest when it shows up somewhere in the host. - - (2) hostbus+hostport -- match for a specific physical port in the - host, any device which is plugged in there gets passed to the - guest. - - (3) hostbus+hostaddr -- most useful for ad-hoc pass through as the - hostaddr isn't stable, the next time you plug in the device it - gets a new one ... - -Note that USB 1.1 devices are handled by UHCI/OHCI and USB 2.0 by -EHCI. That means a device plugged into the very same physical port -may show up on different buses depending on the speed. The port I'm -using for testing is bus 1 + port 1 for 2.0 devices and bus 3 + port 1 -for 1.1 devices. Passing through any device plugged into that port -and also assign them to the correct bus can be done this way: - - qemu -M pc ${otheroptions} \ - -usb \ - -device usb-ehci,id=ehci \ - -device usb-host,bus=usb-bus.0,hostbus=3,hostport=1 \ - -device usb-host,bus=ehci.0,hostbus=1,hostport=1 - -enjoy, - Gerd - --- -Gerd Hoffmann diff --git a/MAINTAINERS b/MAINTAINERS index b1f8e82befc6..2089e71007d6 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1837,7 +1837,6 @@ F: hw/usb/* F: stubs/usb-dev-stub.c F: tests/qtest/usb-*-test.c F: docs/system/devices/usb.rst -F: docs/usb-storage.txt F: include/hw/usb.h F: include/hw/usb/ diff --git a/docs/system/devices/usb.rst b/docs/system/devices/usb.rst index bab0cd3fdfd1..afb7d6c2268d 100644 --- a/docs/system/devices/usb.rst +++ b/docs/system/devices/usb.rst @@ -300,3 +300,52 @@ are not supported yet. When relaunching QEMU, you may have to unplug and plug again the USB device to make it work again (this is a bug). + +``usb-host`` properties for specifying the host device +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The example above uses the ``vendorid`` and ``productid`` to +specify which host device to pass through, but this is not +the only way to specify the host device. ``usb-host`` supports +the following properties: + +``hostbus=`` + Specifies the bus number the device must be attached to +``hostaddr=`` + Specifies the device address the device got assigned by the guest os +``hostport=`` + Specifies the physical port the device is attached to +``vendorid=`` + Specifies the vendor ID of the device +``productid=`` + Specifies the product ID of the device. + +In theory you can combine all these properties as you like. In +practice only a few combinations are useful: + +- ``vendorid`` and ``productid`` -- match for a specific device, pass it to + the guest when it shows up somewhere in the host. + +- ``hostbus`` and ``hostport`` -- match for a specific physical port in the + host, any device which is plugged in there gets passed to the + guest. + +- ``hostbus`` and ``hostaddr`` -- most useful for ad-hoc pass through as the + hostaddr isn't stable. The next time you plug the device into the host it + will get a new hostaddr. + +Note that on the host USB 1.1 devices are handled by UHCI/OHCI and USB +2.0 by EHCI. That means different USB devices plugged into the very +same physical port on the host may show up on different host buses +depending on the speed. Supposing that devices plugged into a given +physical port appear as bus 1 + port 1 for 2.0 devices and bus 3 + port 1 +for 1.1 devices, you can pass through any device plugged into that port +and also assign it to the correct USB bus in QEMU like this: + +.. parsed-literal:: + + |qemu_system| -M pc [...] \\ + -usb \\ + -device usb-ehci,id=ehci \\ + -device usb-host,bus=usb-bus.0,hostbus=3,hostport=1 \\ + -device usb-host,bus=ehci.0,hostbus=1,hostport=1