From patchwork Fri Dec 9 16:17:13 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Cedric Bosdonnat X-Patchwork-Id: 9468595 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 44811607DA for ; Fri, 9 Dec 2016 16:20:00 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 311C328650 for ; Fri, 9 Dec 2016 16:20:00 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 25B5328658; Fri, 9 Dec 2016 16:20:00 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-4.2 required=2.0 tests=BAYES_00, RCVD_IN_DNSWL_MED autolearn=ham version=3.3.1 Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) (using TLSv1.2 with cipher AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id 8791428650 for ; Fri, 9 Dec 2016 16:19:56 +0000 (UTC) Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cFNrb-0008ER-CN; Fri, 09 Dec 2016 16:17:35 +0000 Received: from mail6.bemta5.messagelabs.com ([195.245.231.135]) by lists.xenproject.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cFNrZ-0008B6-K7 for xen-devel@lists.xen.org; Fri, 09 Dec 2016 16:17:33 +0000 Received: from [85.158.139.211] by server-6.bemta-5.messagelabs.com id C3/DC-14841-C19DA485; Fri, 09 Dec 2016 16:17:32 +0000 X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFprIIsWRWlGSWpSXmKPExsVyuP0uq67kTa8 Ig3mzxCyWfFzM4sDocXT3b6YAxijWzLyk/IoE1ozX0yYyFTy1qOi/cIi9gfG4XhcjF4eQwBJG ibONf5m7GDk52ATsJbr+HGUCsUUEpCWufb7MCFLELLCZUeL85IksIAlhAS+JfcfawGwWAVWJL 68/M4LYvAKWEo0vetlBbAkBeYldbRdZQWxOoPils1/A4kICFhJLFp5nhagXlDg58wnQHA6gBe oS6+cJgYSZgVqbt85mnsDIOwtJ1SyEqllIqhYwMq9i1ChOLSpLLdI1tNRLKspMzyjJTczM0TU 0MNXLTS0uTkxPzUlMKtZLzs/dxAgMqnoGBsYdjI/6/Q4xSnIwKYnyFjN5RQjxJeWnVGYkFmfE F5XmpBYfYpTh4FCS4L1/HSgnWJSanlqRlpkDDG+YtAQHj5IIb8ANoDRvcUFibnFmOkTqFKOil DhvIkifAEgiozQPrg0WU5cYZaWEeRkZGBiEeApSi3IzS1DlXzGKczAqCfM+AJnCk5lXAjf9Fd BiJqDF8264gywuSURISTUw9kzincFzfcZXn9ys0I+dByw3Ru1Y+YL7VUHoglnf9HiP3p9cnaW S/mS57P/Kqrd15/s3ck66P3HZkg+GzksFtyYnh8+vUa0ObHNYF6ST+tvqTanyxnkf/0Sujlji sWGOWO5hu4mrhOPEvqUV5n3aN5sj9Ntenl6vomnXVZ/e/7h7Y7ni5NtLE5VYijMSDbWYi4oTA b//EiakAgAA X-Env-Sender: cbosdonnat@suse.com X-Msg-Ref: server-12.tower-206.messagelabs.com!1481300246!38337122!1 X-Originating-IP: [195.135.221.5] X-SpamReason: No, hits=0.0 required=7.0 tests= X-StarScan-Received: X-StarScan-Version: 9.1.1; banners=-,-,- X-VirusChecked: Checked Received: (qmail 32950 invoked from network); 9 Dec 2016 16:17:26 -0000 Received: from smtp.nue.novell.com (HELO smtp.nue.novell.com) (195.135.221.5) by server-12.tower-206.messagelabs.com with DHE-RSA-AES256-GCM-SHA384 encrypted SMTP; 9 Dec 2016 16:17:26 -0000 Received: from laptop.vms (mhy71-2-88-167-63-197.fbx.proxad.net [88.167.63.197]) by smtp.nue.novell.com with ESMTP (TLS encrypted); Fri, 09 Dec 2016 17:17:28 +0100 From: =?UTF-8?q?C=C3=A9dric=20Bosdonnat?= To: xen-devel@lists.xen.org Date: Fri, 9 Dec 2016 17:17:13 +0100 Message-Id: <20161209161714.23866-11-cbosdonnat@suse.com> X-Mailer: git-send-email 2.11.0 In-Reply-To: <20161209161714.23866-1-cbosdonnat@suse.com> References: <20161209161714.23866-1-cbosdonnat@suse.com> MIME-Version: 1.0 Cc: Andrew Cooper , Ian Jackson , Wei Liu , =?UTF-8?q?C=C3=A9dric=20Bosdonnat?= Subject: [Xen-devel] [PATCH 10/11] docs: move pci-device-reservations from misc to man X-BeenThere: xen-devel@lists.xen.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Errors-To: xen-devel-bounces@lists.xen.org Sender: "Xen-devel" X-Virus-Scanned: ClamAV using ClamSMTP pci-device-reservations is references in xl.cfg(5), convert it as a man page in pod format. The name is now prefixed with 'xen-' to avoid possible name conflicts. Signed-off-by: Cédric Bosdonnat Acked-by: Wei Liu --- docs/man/xen-pci-device-reservations.pod.7 | 84 ++++++++++++++++++++++++++++++ docs/man/xl.cfg.pod.5.in | 2 +- docs/misc/pci-device-reservations.txt | 58 --------------------- 3 files changed, 85 insertions(+), 59 deletions(-) create mode 100644 docs/man/xen-pci-device-reservations.pod.7 delete mode 100644 docs/misc/pci-device-reservations.txt diff --git a/docs/man/xen-pci-device-reservations.pod.7 b/docs/man/xen-pci-device-reservations.pod.7 new file mode 100644 index 0000000000..dac92764fc --- /dev/null +++ b/docs/man/xen-pci-device-reservations.pod.7 @@ -0,0 +1,84 @@ +=head1 Description + +PCI vendor ID 0x5853 has been reserved for use by Xen systems in order to +advertise certain virtual hardware to guest virtual machines. The primary +use of this is with device ID 0x0001 to advertise the Xen Platform PCI +device - the presence of this virtual device enables a guest Operating +System (subject to the availability of suitable drivers) to make use of +paravirtualisation features such as disk and network devices etc. + +Some Xen vendors wish to provide alternative and/or additional guest drivers +that can bind to virtual devices[1]. This may be done using the Xen PCI +vendor ID of 0x5853 and Xen-vendor/device specific PCI device IDs. This file +records reservations made within the device ID range in order to avoid +multiple Xen vendors using conflicting IDs. + +=head1 Guidelines + +=over 4 + +=item 1. A vendor may request a range of device IDs by submitting a patch to + this file. + +=item 2. Vendor allocations should be in the range 0xc000-0xfffe to reduce the + possibility of clashes with community IDs assigned from the bottom up. + +=item 3. The vendor is responsible for allocations within the range and should + try to record specific device IDs in PCI ID databases such as + http://pciids.sourceforge.net and http//www.pcidatabase.com + +=back + +=head1 Reservations + + range | vendor/product + --------------+-------------------------------------------------------------- + 0x0001 | (Xen Platform PCI device) + 0x0002 | Citrix XenServer (grandfathered allocation for XenServer 6.1) + 0xc000-0xc0ff | Citrix XenServer + 0xc100-0xc1ff | Citrix XenClient + +=head1 Notes + +=over 4 + +=item 1. + +Upstream QEMU provides a parameterized device called xen-pvdevice that +can be used to host guest drivers. Execute: + + qemu-system-i386 -device xen-pvdevice,help + +for a list of all parameters. The following parameters are relevant to +driver binding: + +=over 4 + +=item vendor-id (default 0x5853) + +The PCI vendor ID and subsystem vendor ID of the device. + +=item device-id (must be specified) + +The PCI device ID and subsystem device ID of the device. + +=item revision (default 0x01) + +The PCI revision of the device + +=back + +Also the size parameter (default 0x400000) can be used to specify the +size of the single MMIO BAR that the device exposes. This area may be +used by drivers for mapping grant tables, etc. + +Note that the presence of the Xen Platform PCI device is generally a +pre-requisite for an additional xen-pvdevice as it is the platform +device that provides that IO ports necessary for unplugging emulated +devices. See hvm-emulated-unplug.markdown for details of the IO ports +and unplug protocol. + +libxl provides support for creation of a single additional xen-pvdevice. +See the vendor_device parameter in xl.cfg(5). + +=back diff --git a/docs/man/xl.cfg.pod.5.in b/docs/man/xl.cfg.pod.5.in index 94eada381f..0dac6f1d9a 100644 --- a/docs/man/xl.cfg.pod.5.in +++ b/docs/man/xl.cfg.pod.5.in @@ -1894,7 +1894,7 @@ specified, enabling the use of XenServer PV drivers in the guest. =back This parameter only takes effect when device_model_version=qemu-xen. -See F for more information. +See L for more information. =back diff --git a/docs/misc/pci-device-reservations.txt b/docs/misc/pci-device-reservations.txt deleted file mode 100644 index 9d6d780ace..0000000000 --- a/docs/misc/pci-device-reservations.txt +++ /dev/null @@ -1,58 +0,0 @@ -PCI vendor ID 0x5853 has been reserved for use by Xen systems in order to -advertise certain virtual hardware to guest virtual machines. The primary -use of this is with device ID 0x0001 to advertise the Xen Platform PCI -device - the presence of this virtual device enables a guest Operating -System (subject to the availability of suitable drivers) to make use of -paravirtualisation features such as disk and network devices etc. - -Some Xen vendors wish to provide alternative and/or additional guest drivers -that can bind to virtual devices[1]. This may be done using the Xen PCI -vendor ID of 0x5853 and Xen-vendor/device specific PCI device IDs. This file -records reservations made within the device ID range in order to avoid -multiple Xen vendors using conflicting IDs. - -Guidelines - 1. A vendor may request a range of device IDs by submitting a patch to - this file. - 2. Vendor allocations should be in the range 0xc000-0xfffe to reduce the - possibility of clashes with community IDs assigned from the bottom up. - 3. The vendor is responsible for allocations within the range and should - try to record specific device IDs in PCI ID databases such as - http://pciids.sourceforge.net and http//www.pcidatabase.com - -Reservations -============ - - range | vendor/product ---------------+-------------------------------------------------------------- -0x0001 | (Xen Platform PCI device) -0x0002 | Citrix XenServer (grandfathered allocation for XenServer 6.1) -0xc000-0xc0ff | Citrix XenServer -0xc100-0xc1ff | Citrix XenClient - -[1] Upstream QEMU provides a parameterized device called xen-pvdevice that - can be used to host guest drivers. Execute: - - qemu-system-i386 -device xen-pvdevice,help - - for a list of all parameters. The following parameters are relevant to - driver binding: - - vendor-id (default 0x5853): The PCI vendor ID and subsystem vendor - ID of the device. - device-id (must be specified): The PCI device ID and subsystem device - ID of the device. - revision (default 0x01): The PCI revision of the device - - Also the size parameter (default 0x400000) can be used to specify the - size of the single MMIO BAR that the device exposes. This area may be - used by drivers for mapping grant tables, etc. - - Note that the presence of the Xen Platform PCI device is generally a - pre-requisite for an additional xen-pvdevice as it is the platform - device that provides that IO ports necessary for unplugging emulated - devices. See hvm-emulated-unplug.markdown for details of the IO ports - and unplug protocol. - - libxl provides support for creation of a single additional xen-pvdevice. - See the vendor_device parameter in xl.cfg(5).