From nobody Fri May 10 20:40:54 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1627481942; cv=none; d=zohomail.com; s=zohoarc; b=FtFvpjch+x0FLsvLL21c10s/9QDZ/rSIlc19RR6JNeijsCkw5atFS714523UprjazA/lNo16XAJmzA/EnVGnx7rdVZIfFF2mTmqGAr64mWXqZRA8hhPmsIKews40yQzasHsmegKp5SRkfrN4VvWr8pjzVckDKBDf4amPgk2Orj4= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1627481942; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=SlUzvXZUcVgIl02AlwheprRJgr/gy9rUBBkrbVbr+0E=; b=GN+rU7JK1NShBPlvtHYiu/4TiGpfZN88lBsCBVewp4ABPeM6lrTOxpaWJruaTuQJD84W904Vpz29LG0JjJEP5bhzwUUJAltrjZ96YpsikW1qlj/TKEH9yRaPkgMN4YPs8mkPPFxB8jHGKoQhco1XqhjGIkb1c6IsIOTwWGJUj0s= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 162748194210461.4395560134916; Wed, 28 Jul 2021 07:19:02 -0700 (PDT) Received: from localhost ([::1]:41236 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m8kOi-0001xz-N2 for importer@patchew.org; Wed, 28 Jul 2021 10:19:00 -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) 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) 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) 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 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; 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+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) X-ZM-MESSAGEID: 1627481943189100001 Content-Type: text/plain; charset="utf-8" We already have a section on USB in the rST manual; fold the information in docs/usb-storage.txt into it. We add 'format=3Draw' 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: =20 ``usb-storage,drive=3Ddrive_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=3Dnone,id=3Dstick,format=3Draw,file=3D/path/to/file.img = \\ + -device nec-usb-xhci,id=3Dxhci \\ + -device usb-storage,bus=3Dxhci.0,drive=3Dstick =20 ``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=3Dnone,id=3Duas-disk1,format=3Draw,file=3D/path/to/file1.= img \\ + -drive if=3Dnone,id=3Duas-disk2,format=3Draw,file=3D/path/to/file2.= img \\ + -drive if=3Dnone,id=3Duas-cdrom,media=3Dcdrom,format=3Draw,file=3D/= path/to/image.iso \\ + -device nec-usb-xhci,id=3Dxhci \\ + -device usb-uas,id=3Duas,bus=3Dxhci.0 = \\ + -device scsi-hd,bus=3Duas.0,scsi-id=3D0,lun=3D0,drive=3Duas-disk1 = \\ + -device scsi-hd,bus=3Duas.0,scsi-id=3D0,lun=3D1,drive=3Duas-disk2 = \\ + -device scsi-cd,bus=3Duas.0,scsi-id=3D0,lun=3D5,drive=3Duas-cdrom =20 ``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``. =20 ``usb-mtp,rootdir=3Ddir`` 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 =20 +Hotplugging USB storage +~~~~~~~~~~~~~~~~~~~~~~~ + +The ``usb-bot`` and ``usb-uas`` devices can be hotplugged. In the hotplug +case they are added with ``attached =3D 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=3Dfoo`` +#. ``device-add scsi-{hd,cd},bus=3Dfoo.0,lun=3D0`` +#. optionally add more devices (luns 1 ... 15) +#. ``scripts/qmp/qom-set foo.attached =3D true`` + .. _host_005fusb_005fdevices: =20 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=3Dnone,id=3Dstick,file=3D/path/to/file.img \ - -device nec-usb-xhci,id=3Dxhci \ - -device usb-storage,bus=3Dxhci.0,drive=3Dstick - - -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=3Dnone,id=3Duas-disk1,file=3D/path/to/file1.img = \ - -drive if=3Dnone,id=3Duas-disk2,file=3D/path/to/file2.img = \ - -drive if=3Dnone,id=3Duas-cdrom,media=3Dcdrom,file=3D/path/to/image= .iso \ - -device nec-usb-xhci,id=3Dxhci \ - -device usb-uas,id=3Duas,bus=3Dxhci.0 = \ - -device scsi-hd,bus=3Duas.0,scsi-id=3D0,lun=3D0,drive=3Duas-disk1 = \ - -device scsi-hd,bus=3Duas.0,scsi-id=3D0,lun=3D1,drive=3Duas-disk2 = \ - -device scsi-cd,bus=3Duas.0,scsi-id=3D0,lun=3D5,drive=3Duas-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 =3D -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=3Dfoo - (2) device-add scsi-{hd,cd},bus=3Dfoo.0,lun=3D0 - (2b) optionally add more devices (luns 1 ... 15). - (3) scripts/qmp/qom-set foo.attached =3D 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/ --=20 2.20.1 From nobody Fri May 10 20:40:54 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1627481842; cv=none; d=zohomail.com; s=zohoarc; b=Paabc6Rr1pU3uXHbtNxjhbcnB5DWJNnRA2oSnRSDI7lHKKZ0r0PpcCFKl/phNaLNykbZCDxXvKrQkWkZxGTjS17+UIlJyv9DkhkLk+I57FYZqmq5OpA64SWdT1nsmSyc1kq+FvuAQSqmKh4LbAeqWYaczLIxRlcddrK+ezwldQ0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1627481842; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=+UN3ZxKmtOqLJCCR6zn7wm0RZkJocDT1JRQPYi7dhl8=; b=Q0MBg5CqxpPoXg11fAuuxE5a2z1PAqCTTcsNx7fU2RZRl/UiSQKHlUdlJLDIY1zIjMNu/BKRzeDoxM0Ir4nXzV60i66VVrLJROelDpTcg+9XWJR+L9PDEeHSk6g2qfTxGSLNXZmAHso8Pwa/OiUYXFhvOJN79CEh/mt/iRk56Wo= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1627481842748883.1238189011957; Wed, 28 Jul 2021 07:17:22 -0700 (PDT) Received: from localhost ([::1]:36664 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m8kN7-0007Ha-Jb for importer@patchew.org; Wed, 28 Jul 2021 10:17:21 -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) 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) 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) 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 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; 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+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) X-ZM-MESSAGEID: 1627481844754100003 Content-Type: text/plain; charset="utf-8" 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 wo= rks with certain host operating systems). QEMU will automatically create and connect virtual USB hubs as necessary to connect multiple USB devices. =20 +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=3D 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=3Dehci``. 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=3Dnone,id=3Dusbstick,format=3Draw,file=3D/path/to/image = \\ + -usb \\ + -device usb-ehci,id=3Dehci \\ + -device usb-tablet,bus=3Dusb-bus.0 \\ + -device usb-storage,bus=3Dehci.0,drive=3Dusbstick + +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=3Dehci.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: =20 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 @@ =20 -USB Quick Start -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - -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=3D 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=3Dehci". 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=3Dnone,id=3Dusbstick,file=3D/path/to/image \ - -usb \ - -device usb-ehci,id=3Dehci \ - -device usb-tablet,bus=3Dusb-bus.0 \ - -device usb-storage,bus=3Dehci.0,drive=3Dusbstick - -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=3Dehci.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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 --=20 2.20.1 From nobody Fri May 10 20:40:54 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1627481841; cv=none; d=zohomail.com; s=zohoarc; b=VSLFagJucW8TW73VZxUcBKtDuyiQp1tYPNID4NIodJ0AoS8cx9dW8kqCQPDCFA/yeqt+B6v57eq249iN1j1VUFiu7sxY6gMRRNATdwTULQ4eB+Cjr58YimEHhGFXsKfW8dQhwNYqZBKlfxtgOncD0ouTmxcOIW8ay6v+0SIYLZI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1627481841; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=kvZcy/pQqom8ti6GfZ9pyXdeZh+6hzPg79+N3EGB/4Q=; b=AsKcGMKiV/QXV/UluTHooOKNz0dKTIDLbf538cjwA/9gTATVT8hCmR6d/DEyUUZuiv5Fwfmhv1qH7HJMfAd8RIU22pQFPfYgyb/tAO4R4UkL8A9uflOHfzqINUcYyQgKjBH9EUATzaZFxfV87m3Hgx2Rn8qkIL5FgjvCRkBVQp4= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1627481841771420.83751119109604; Wed, 28 Jul 2021 07:17:21 -0700 (PDT) Received: from localhost ([::1]:36610 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m8kN6-0007FU-OZ for importer@patchew.org; Wed, 28 Jul 2021 10:17:20 -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) 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) 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) 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 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; 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+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) X-ZM-MESSAGEID: 1627481844304100001 Content-Type: text/plain; charset="utf-8" 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. Availabl= e devices are: ``u2f-{emulated,passthru}`` Universal Second Factor device =20 +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=3Dusb-bus.0,port=3D1 + +Plugging a hub into UHCI port 2 works like this:: + + -device usb-hub,bus=3Dusb-bus.0,port=3D2 + +Plugging a virtual USB stick into port 4 of the hub just plugged works +this way:: + + -device usb-storage,bus=3Dusb-bus.0,port=3D2.4,drive=3D... + +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=3Dusb-bus.0,port=3D1,id=3Dmy-tabl= et + (qemu) device_del my-tablet + Hotplugging USB storage ~~~~~~~~~~~~~~~~~~~~~~~ =20 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-ho= st) and the QEMU USB subsystem gained a few capabilities which are available only via qdev properties, i,e. when using '-device'. =20 - -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=3Dusb-bus.0,port=3D1 - -Plugging a hub into UHCI port 2 works like this: - - -device usb-hub,bus=3Dusb-bus.0,port=3D2 - -Plugging a virtual USB stick into port 4 of the hub just plugged works -this way: - - -device usb-storage,bus=3Dusb-bus.0,port=3D2.4,drive=3D... - -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=3Dusb-bus.0,port=3D1,id=3Dmy-tabl= et - (qemu) device_del my-tablet - -... when unplugging it with device_del. - - USB pass through hints ---------------------- =20 --=20 2.20.1 From nobody Fri May 10 20:40:54 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1627481981; cv=none; d=zohomail.com; s=zohoarc; b=Gk7pUYJu1SROjcICZFOlZ/7mUqS5955y9UOsas0KZeB2qjGer0mj9Rnk9ktwIWmBSP20OE1aMTfRQAzDSXRQyksjVKUDt6T1SqWStZsjKV3knoyUqqT+KkVe+HmR1MvLNPjMxImvob6jq3lNSlL3rG7K1BvealPDBRpK3CJ5hHw= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1627481981; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=cOFMT94+QgDAwNgiL7YNxb6ny/F84wGTRdXmMFu22r0=; b=evRskl3X+h7l79CPx+XXkhP5wG/5yzC6ZTsZLCmFmru0mJDe+73C0nK2XDzKLG9ZObMyl70ol4thNZPfHTmNEfGSnvpxJbHOMgXzOAhRYwxuKxWa1XNDHGCvpq0wUl5Ky8lllJ4eLWd+LQezoz5beF+1pNgXljMJjxGHcLgFzE8= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1627481981134470.39514394240257; Wed, 28 Jul 2021 07:19:41 -0700 (PDT) Received: from localhost ([::1]:44024 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m8kPM-0003r9-2n for importer@patchew.org; Wed, 28 Jul 2021 10:19:40 -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) 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) 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) 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 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; 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+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) X-ZM-MESSAGEID: 1627481981982100001 Content-Type: text/plain; charset="utf-8" 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. =20 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=3D`` + Specifies the bus number the device must be attached to +``hostaddr=3D`` + Specifies the device address the device got assigned by the guest os +``hostport=3D`` + Specifies the physical port the device is attached to +``vendorid=3D`` + Specifies the vendor ID of the device +``productid=3D`` + 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 t= he + 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=3Dehci \\ + -device usb-host,bus=3Dusb-bus.0,hostbus=3D3,hostport=3D1 \\ + -device usb-host,bus=3Dehci.0,hostbus=3D1,hostport=3D1 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 -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - -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=3D -- Specifies the bus number the device must be attached - to. - - hostaddr=3D -- Specifies the device address the device got - assigned by the guest os. - - hostport=3D -- Specifies the physical port the device is attached - to. - - vendorid=3D -- Specifies the vendor ID of the device. - productid=3D -- 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=3Dehci \ - -device usb-host,bus=3Dusb-bus.0,hostbus=3D3,hostport=3D1 \ - -device usb-host,bus=3Dehci.0,hostbus=3D1,hostport=3D1 - -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/ =20 --=20 2.20.1