From nobody Sat May 4 12:15:32 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) client-ip=208.118.235.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) by mx.zohomail.com with SMTPS id 152820322842390.48608563290861; Tue, 5 Jun 2018 05:53:48 -0700 (PDT) Received: from localhost ([::1]:46455 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fQBT9-0002Dq-Bz for importer@patchew.org; Tue, 05 Jun 2018 08:53:47 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:47297) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fQBSI-0001t9-R4 for qemu-devel@nongnu.org; Tue, 05 Jun 2018 08:52:56 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fQBSF-0006nt-Nd for qemu-devel@nongnu.org; Tue, 05 Jun 2018 08:52:54 -0400 Received: from mx3-rdu2.redhat.com ([66.187.233.73]:38404 helo=mx1.redhat.com) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1fQBSF-0006nV-Hy for qemu-devel@nongnu.org; Tue, 05 Jun 2018 08:52:51 -0400 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.rdu2.redhat.com [10.11.54.3]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id BB51A4075384 for ; Tue, 5 Jun 2018 12:52:50 +0000 (UTC) Received: from sirius.home.kraxel.org (ovpn-116-24.ams2.redhat.com [10.36.116.24]) by smtp.corp.redhat.com (Postfix) with ESMTP id 3B0A6112D164; Tue, 5 Jun 2018 12:52:46 +0000 (UTC) Received: by sirius.home.kraxel.org (Postfix, from userid 1000) id 7C799A0DFD; Tue, 5 Jun 2018 14:52:45 +0200 (CEST) From: Gerd Hoffmann To: qemu-devel@nongnu.org Date: Tue, 5 Jun 2018 14:52:45 +0200 Message-Id: <20180605125245.32612-1-kraxel@redhat.com> X-Scanned-By: MIMEDefang 2.78 on 10.11.54.3 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.7]); Tue, 05 Jun 2018 12:52:50 +0000 (UTC) X-Greylist: inspected by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.7]); Tue, 05 Jun 2018 12:52:50 +0000 (UTC) for IP:'10.11.54.3' DOMAIN:'int-mx03.intmail.prod.int.rdu2.redhat.com' HELO:'smtp.corp.redhat.com' FROM:'kraxel@redhat.com' RCPT:'' X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-Received-From: 66.187.233.73 Subject: [Qemu-devel] [PATCH] usb: update docs X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Gerd Hoffmann , Markus Armbruster Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail: RSF_0 Z_629925259 SPT_0 Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" xhci is rock solid meanwhile. So move it up in the docs and feature it as prefered usb host adapter, instead of the old shy version saying "you might want try ...". While being at it rework the text on ehci and companion controllers too. Signed-off-by: Gerd Hoffmann --- docs/usb2.txt | 80 ++++++++++++++++++++++++++++++++++---------------------= ---- 1 file changed, 46 insertions(+), 34 deletions(-) diff --git a/docs/usb2.txt b/docs/usb2.txt index 09df45b5b1..30055a2258 100644 --- a/docs/usb2.txt +++ b/docs/usb2.txt @@ -1,16 +1,42 @@ =20 -USB 2.0 Quick Start -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +USB Quick Start +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -The QEMU EHCI Adapter can be used with and without companion -controllers. See below for the companion controller mode. +xhci controller support +----------------------- =20 -When not running in companion controller mode there are two completely -separate USB busses: 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. +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) I recommend using it: =20 -The '-usb' switch will make qemu create the UHCI controller as part of + 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) being 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 convinient 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 busses: 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". =20 You can use the standard -device switch to add a EHCI controller to @@ -37,37 +63,23 @@ device to the EHCI adapter. Companion controller support ---------------------------- =20 -Companion controller support has been added recently. The operational -model described above with two completely separate busses still works -fine. Additionally the UHCI and OHCI controllers got the ability to -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. +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. =20 -There is a config file in docs which will do all this for you, just -try ... +There is a config file in docs which will do all this for +you, just try ... =20 qemu -readconfig docs/config/ich9-ehci-uhci.cfg =20 ... then use "bus=3Dehci.0" to assign your usb devices to that bus. =20 - -xhci controller support ------------------------ - -There is also xhci host controller support available. It got a lot -less testing than ehci and there are a bunch of known limitations, so -ehci may work better for you. On the other hand the xhci hardware -design is much more virtualization-friendly, thus xhci emulation uses -less resources (especially cpu). If you want to give xhci a try -use this to add the host controller ... - - qemu -device nec-usb-xhci,id=3Dxhci - -... then use "bus=3Dxhci.0" when assigning usb devices. +Using the '-usb' switch for 'q35' machines will create a simliar +usb controller configuration. =20 =20 More USB tips & tricks --=20 2.9.3