From patchwork Wed Jul 28 14:14:54 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 1510873 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=ESXvtD8R; dkim-atps=neutral Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 4GZbNc1NMSz9sRR for ; Thu, 29 Jul 2021 00:18:08 +1000 (AEST) Received: from localhost ([::1]:37342 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m8kNm-0007l1-6c for incoming@patchwork.ozlabs.org; Wed, 28 Jul 2021 10:18:02 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:57294) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m8kKw-0004O3-38 for qemu-devel@nongnu.org; Wed, 28 Jul 2021 10:15:06 -0400 Received: from mail-wm1-x32e.google.com ([2a00:1450:4864:20::32e]:44004) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1m8kKt-0007TR-KR for qemu-devel@nongnu.org; Wed, 28 Jul 2021 10:15:05 -0400 Received: by mail-wm1-x32e.google.com with SMTP id m20-20020a05600c4f54b029024e75a15716so1799561wmq.2 for ; Wed, 28 Jul 2021 07:15:03 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=SlUzvXZUcVgIl02AlwheprRJgr/gy9rUBBkrbVbr+0E=; b=ESXvtD8R2ECnxUpUG1fQiqDercKSUIUXnTs255iCmOCXFStAhy/1CephFhAHamqzLk 48HCvsgZvFPw70+5selfRQ91ODU9uPgG8OeSvCcPEbODygky2nI8vpMO4eS6ECP4dFA9 FzXaNvo4hs8swo5U2wVM3gbX9bxx7f+O6yNWWcreILFsiCkjjpIjzdTXRpvXaQuyOSoe vLYSjIWJM8S+ld6VHQYNRaqdEwJs48UEGDaulve84GURAdEvJ2OAHitgdXlbKfrQxXrF IkliXT0US/7oaYWXF1TQDPTLX6YwOk0IVbZUewT3xsDAnEdY9qvMo4lckkok4JB3tSZx Reqw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=SlUzvXZUcVgIl02AlwheprRJgr/gy9rUBBkrbVbr+0E=; b=WqmfNI3D9HWWJYpSIx4d4ElSfPXZWPlrpf2v/g9sJ31R65FEOJGlG7Die+EqxB5F74 QBXMFjWscSmwBgDYZ8TFQxuwMJUysmZ7F0ufCJbQD8ffMHwDDchMH3op462VvP9gry/K 5Qt808uM9qDz/YpcrBoXxS/kgX/roqXpOBAViDhrV0n9meLBgm2aeMAxUu7f8sVsOYJg JyYwqzX1yR0EWgPaWzZyNYvBquGtsSD38Lh6/lanlHBQDru+yMnLp+wK78pHbIj9hFbx RV70lksTDWpL6jdiZm4C62AuTMkWXE///+0AtFVORasbe3/iFdNpWDo6MtSEO0TZA6U3 YiXA== X-Gm-Message-State: AOAM531J5rnbNvE8oR2tCykHSNxgkqLcxBt8QKxFujA4xTy8gvRt7aDb aDGnoMbkPdzLZDscgMRcnwlxu4v60/Kq8Q== X-Google-Smtp-Source: ABdhPJxNyyvkHWhotzkxZnfE4F0iy+bV7my8sx+f7stGgljF+6uKeASW69REG98oLVGINTsL7d3FSA== X-Received: by 2002:a05:600c:2251:: with SMTP id a17mr2098108wmm.189.1627481701866; Wed, 28 Jul 2021 07:15:01 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d8sm7598247wrv.20.2021.07.28.07.15.01 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 28 Jul 2021 07:15:01 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 1/4] docs: Incorporate information in usb-storage.txt into rST manual Date: Wed, 28 Jul 2021 15:14:54 +0100 Message-Id: <20210728141457.14825-2-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20210728141457.14825-1-peter.maydell@linaro.org> References: <20210728141457.14825-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::32e; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x32e.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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: Gerd Hoffmann Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" 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 --- docs/system/devices/usb.rst | 57 ++++++++++++++++++++++++++++++----- docs/usb-storage.txt | 59 ------------------------------------- MAINTAINERS | 2 +- 3 files changed, 51 insertions(+), 67 deletions(-) delete mode 100644 docs/usb-storage.txt diff --git a/docs/system/devices/usb.rst b/docs/system/devices/usb.rst index eeab78dcfbe..7da142ecbb9 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 diff --git a/docs/usb-storage.txt b/docs/usb-storage.txt deleted file mode 100644 index 551af6f88bb..00000000000 --- 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 ae9c2680134..bb82bebf59e 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1840,7 +1840,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/ From patchwork Wed Jul 28 14:14:55 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 1510871 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=obzU5glN; dkim-atps=neutral Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 4GZbLL1PvLz9sRR for ; Thu, 29 Jul 2021 00:16:10 +1000 (AEST) Received: from localhost ([::1]:60944 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m8kLv-0004U3-MM for incoming@patchwork.ozlabs.org; Wed, 28 Jul 2021 10:16:07 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:57320) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m8kKx-0004RA-Ny for qemu-devel@nongnu.org; Wed, 28 Jul 2021 10:15:08 -0400 Received: from mail-wr1-x42b.google.com ([2a00:1450:4864:20::42b]:34751) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1m8kKv-0007UT-Hz for qemu-devel@nongnu.org; Wed, 28 Jul 2021 10:15:07 -0400 Received: by mail-wr1-x42b.google.com with SMTP id r2so2783730wrl.1 for ; Wed, 28 Jul 2021 07:15:05 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=+UN3ZxKmtOqLJCCR6zn7wm0RZkJocDT1JRQPYi7dhl8=; b=obzU5glNhTiaSbVEcnBl6EtTkacIa5mqHvtXJfh29Cd4egu9sKo0ilpQ9cO7O6iUn5 242ig0VeP3jHXQB6hIdckUcR5bG0HZgji/TVmP7cTSGVL3HWW3+TsytOJnU/sbkxDe5S CEc6yj/ppnbY7NpQC+s1Mvxh8ECn+dsEkPisr33EbXCpJTwyNAyS776ykmuQl1+otk8O a+gRzT3Y8V9HnfaPADP4jypI3k159Ggjt+To9q4eTJ0u2sLGo3zVgg89OJxdEdXw6DpJ uL+BlXK/6ytgCLQpU6U2uNIAHNpmOu7sHgH8g8oTCqLcOZke1RmRfsbaiNCCtugA3CN8 HdHg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=+UN3ZxKmtOqLJCCR6zn7wm0RZkJocDT1JRQPYi7dhl8=; b=BnuG4RTNh70/xsO6QhW2hwEmG62t+7UETaHANrgIm8IoJ5CWcU/67/ZHupJfRqnfO9 XO+C2OkYWy70WHOnvXeULN47IR8RgC1E4RbWwnX2uFQ+Vr7L1qVDnIiGokYYzBBgXjkH sSsCuo7AvuDQ8sfO5qpBWz+dJ+wUnA3qL5uee7QxW+QKP6fWmz5n65C/IRB+/+VPTWBi 28g2FHs8BH9teBUEZ/K2gRfWWcA0wSzK4ngIHM58zoE0n0BEkYK0S/JAH8iBe+YnvQwa VcN9KIMnTKmvYBBztuUv7IZGOY5gQKf2FoHbLGNPScO4HCDhSLDsLuUft9J8AWVCBuI4 o6pQ== X-Gm-Message-State: AOAM531nz8JUrYH4NJKvNAt/JXZueuP82uLqXuC0J8++7NluhyhIcKz4 Njv53FqRwmUTT6bzTEI9q1Y54MyrPsRMVg== X-Google-Smtp-Source: ABdhPJxBo0CrFRoUSW30RLKwqIBZwLxyHD+yjR6GmFWlQuvgKdSPmWJVy7IbJuK+fLYl7M7RkFDp4A== X-Received: by 2002:adf:ff92:: with SMTP id j18mr13902109wrr.334.1627481703976; Wed, 28 Jul 2021 07:15:03 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d8sm7598247wrv.20.2021.07.28.07.15.01 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 28 Jul 2021 07:15:02 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 2/4] docs: Fold usb2.txt USB controller information into usb.rst Date: Wed, 28 Jul 2021 15:14:55 +0100 Message-Id: <20210728141457.14825-3-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20210728141457.14825-1-peter.maydell@linaro.org> References: <20210728141457.14825-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::42b; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x42b.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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: Gerd Hoffmann Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" 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 --- docs/system/devices/usb.rst | 86 +++++++++++++++++++++++++++++++++++++ docs/usb2.txt | 82 ----------------------------------- 2 files changed, 86 insertions(+), 82 deletions(-) diff --git a/docs/system/devices/usb.rst b/docs/system/devices/usb.rst index 7da142ecbb9..9f0e613dcc7 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 diff --git a/docs/usb2.txt b/docs/usb2.txt index 172614d3a7e..adf4ba3f2a0 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 ====================== From patchwork Wed Jul 28 14:14:56 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 1510870 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=Ml0n3oDq; dkim-atps=neutral Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 4GZbLL0ygRz9sCD for ; Thu, 29 Jul 2021 00:16:10 +1000 (AEST) Received: from localhost ([::1]:60946 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m8kLv-0004U5-Js for incoming@patchwork.ozlabs.org; Wed, 28 Jul 2021 10:16:07 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:57324) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m8kKx-0004RI-Uu for qemu-devel@nongnu.org; Wed, 28 Jul 2021 10:15:08 -0400 Received: from mail-wr1-x436.google.com ([2a00:1450:4864:20::436]:42496) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1m8kKw-0007VP-A3 for qemu-devel@nongnu.org; Wed, 28 Jul 2021 10:15:07 -0400 Received: by mail-wr1-x436.google.com with SMTP id j2so2734109wrx.9 for ; Wed, 28 Jul 2021 07:15:05 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=kvZcy/pQqom8ti6GfZ9pyXdeZh+6hzPg79+N3EGB/4Q=; b=Ml0n3oDqGDRZ847XJ5KzemcXYx1GuxjfrzCbSGI0Hb3bQlIiYGunU35r46yo4gNbH0 f6kHA2QB8orGYeHoE2F3qN1cyGVzK+KcKawL5UCtGPUPtzt8gBr+LmZY7Ro/BKUx40GI yJToJfI4pad0sdQj6RFrL3s/zLgL2941EZr+Pd4pbcLKttl3CBSFpP7RAakAW1Z8A+/6 ChNM2H9TDtkQ1jQfTMRDStAoOZkqaIWFXVOnQKuq1foRuVkb1NTOLXxVFA4hI7iZGIX9 tJQf9xjAFPo1pBbyOL647eShqUxc4s4ENkANuMF3+nEQ5+5WwQ0osQka4OjxqmKP6JMI 0qhA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=kvZcy/pQqom8ti6GfZ9pyXdeZh+6hzPg79+N3EGB/4Q=; b=SPz8dbL8iNOQPFdc7WQMXPNu7e65p07cDGZDLlyKpqeTMTbyKv0RxlMFMV8x3PSpxw aB7NLVa+6cG1fjRqW0nOjnY+cQ2iNbZm8PcFnzuEN60ppnszX3ottHTGnzbGecqotc2s BM0GIH4zhsqD6Uq2/iLH1D0hCk6Dwv0hncyiudwRpA65rtIyy3VLENhjb/U/8S+YVp3i LpAWqWeQK5/hHLeGGHqhsHHcw9W7IxWvZqyaG+EfSEA0tGMDC4e17ylcKeQFSv1AViXP YmA5bW+JqIxr7JZc8LXj2ifQqOXZgp7UPKtl9f82tJco2UDSdCBf7VQgN2tw+Bsfxn0L AK9Q== X-Gm-Message-State: AOAM53015gS3U/MLqRFC3WKToyYaR+qbdnS7MfQAxVwogfoVvTtyiFFB ueiSpUr8PzscqnCWCEdR5YiapQSjMWJvVQ== X-Google-Smtp-Source: ABdhPJyxKJpskvhWIq5+EjmVvx7xWVT5LdLW6AYHaUQj4wW0kvXRODfQ5vq/rGvDJH1xON5PFEFjGw== X-Received: by 2002:a5d:4b4e:: with SMTP id w14mr10819702wrs.341.1627481704894; Wed, 28 Jul 2021 07:15:04 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d8sm7598247wrv.20.2021.07.28.07.15.04 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 28 Jul 2021 07:15:04 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 3/4] docs: Fold usb2.txt physical port addressing info into usb.rst Date: Wed, 28 Jul 2021 15:14:56 +0100 Message-Id: <20210728141457.14825-4-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20210728141457.14825-1-peter.maydell@linaro.org> References: <20210728141457.14825-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::436; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x436.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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: Gerd Hoffmann Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" Fold the usb2.txt documentation about specifying which physical port a USB device should use into usb.rst. Signed-off-by: Peter Maydell --- docs/system/devices/usb.rst | 33 +++++++++++++++++++++++++++++++++ docs/usb2.txt | 32 -------------------------------- 2 files changed, 33 insertions(+), 32 deletions(-) diff --git a/docs/system/devices/usb.rst b/docs/system/devices/usb.rst index 9f0e613dcc7..bab0cd3fdfd 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 ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/usb2.txt b/docs/usb2.txt index adf4ba3f2a0..6a88d5314f9 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 ---------------------- From patchwork Wed Jul 28 14:14:57 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 1510877 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=rioTRi6F; dkim-atps=neutral Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 4GZbPm0pCqz9sRR for ; Thu, 29 Jul 2021 00:19:07 +1000 (AEST) Received: from localhost ([::1]:41030 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m8kOm-0001qC-Ss for incoming@patchwork.ozlabs.org; Wed, 28 Jul 2021 10:19:04 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:57332) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m8kKy-0004SO-Sj for qemu-devel@nongnu.org; Wed, 28 Jul 2021 10:15:08 -0400 Received: from mail-wm1-x330.google.com ([2a00:1450:4864:20::330]:38748) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1m8kKw-0007Vo-W4 for qemu-devel@nongnu.org; Wed, 28 Jul 2021 10:15:08 -0400 Received: by mail-wm1-x330.google.com with SMTP id o5-20020a1c4d050000b02901fc3a62af78so4444844wmh.3 for ; Wed, 28 Jul 2021 07:15:06 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=cOFMT94+QgDAwNgiL7YNxb6ny/F84wGTRdXmMFu22r0=; b=rioTRi6FWz66vnekPUs/Y5VWlW+4SrwNXub7t0cDB5OLFrpWsXD7ms8J2dflN5CHz2 Au0Rgl8x5PVtOIzpoQS7wSQxRzxb1jDascqcyhclXbpmEOvLmHeRboJOHY3FJdnYUTG0 3+YKvTkVlbrP4yotWJZiBGGg82YOZxWSTP1FPDbq3m+6yom4SdBOr9LPkxpRj9aaiukr XQY0OWLikzOe5KwaLzCaJpHV1kyu0qQKigec5YFLzQouhjjpZAIBScnejc4mUXT1Uncr l2ssBv7tCO5VMVefUGCjldF5QDjVgxXhIFzonSm1oZJra6dDn76nJ0g2HOKXlMAIrGhb zSRg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=cOFMT94+QgDAwNgiL7YNxb6ny/F84wGTRdXmMFu22r0=; b=eQzmV7Fxda4pYt5Gue7zhI7JNs07Arg3ooMokabvpwSG+tbAuO/i1bODMbJiJHTIGv 0IHB5NtDW4O3raTjSf/UFDIDNUOz8ExloLmw0BKjX+3k+55KI9ypIOn4Fgby3mRKEGzf Uck5BBD5nrT8jsEtAkMHRDmCCG0dd2nfOf0BxVmsevklY+8G/3AOeTYcg0aFnDPZHN1Y Kk5ECA9yz+q//vG1dvp9rbMNBejXzFhCfIsXutk5gxM2rED1puUUDwkuhsOhbLsgaIJ8 2FZz+ujrsp2K+Y6vI/+098fJJAmQFchfeFI26Dh3kDFKnDf1mf/ivugrD0c9o5Dz3Gnh sYVQ== X-Gm-Message-State: AOAM533prxYhY+cUGmPqJPEWn6PHZ2dP9pramO2CCIrE67QdAJp55Ta3 Ewe/dmHylxiLA7mjl8SMB9OLo85NFdJZ0g== X-Google-Smtp-Source: ABdhPJzl2LDM63VWIh89yJYvbOpv62bo9eHqNczHhbI29iovKLmUkedPXLmeNArZ2IkecuFne1B/PA== X-Received: by 2002:a1c:c918:: with SMTP id f24mr13339109wmb.88.1627481705622; Wed, 28 Jul 2021 07:15:05 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d8sm7598247wrv.20.2021.07.28.07.15.05 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 28 Jul 2021 07:15:05 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 4/4] docs: Fold usb2.txt passthrough information into usb.rst Date: Wed, 28 Jul 2021 15:14:57 +0100 Message-Id: <20210728141457.14825-5-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20210728141457.14825-1-peter.maydell@linaro.org> References: <20210728141457.14825-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::330; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x330.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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: Gerd Hoffmann Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" 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 --- docs/system/devices/usb.rst | 49 +++++++++++++++++++++++++++++++ docs/usb2.txt | 58 ------------------------------------- MAINTAINERS | 1 - 3 files changed, 49 insertions(+), 59 deletions(-) delete mode 100644 docs/usb2.txt diff --git a/docs/system/devices/usb.rst b/docs/system/devices/usb.rst index bab0cd3fdfd..afb7d6c2268 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 diff --git a/docs/usb2.txt b/docs/usb2.txt deleted file mode 100644 index 6a88d5314f9..00000000000 --- 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 bb82bebf59e..9359a3db619 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1841,7 +1841,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/