1=head1 NAME
2
3xen-pci-device-reservations - Xen PCI device ID registry
4
5=head1 Description
6
7PCI vendor ID 0x5853 has been reserved for use by Xen systems in order to
8advertise certain virtual hardware to guest virtual machines. The primary
9use of this is with device ID 0x0001 to advertise the Xen Platform PCI
10device - the presence of this virtual device enables a guest Operating
11System (subject to the availability of suitable drivers) to make use of
12paravirtualisation features such as disk and network devices etc.
13XenServer, for Windows machines, may present Xen Platform device with device
14ID 0x0002 instead of 0x0001. Device 0x0001 and 0x0002 should be mutually
15exclusive.
16
17Some Xen vendors wish to provide alternative and/or additional guest drivers
18that can bind to virtual devices[1]. This may be done using the Xen PCI
19vendor ID of 0x5853 and Xen-vendor/device specific PCI device IDs. This file
20records reservations made within the device ID range in order to avoid
21multiple Xen vendors using conflicting IDs.
22
23=head1 Guidelines
24
25=over 4
26
27=item 1. A vendor may request a range of device IDs by submitting a patch to
28         this file.
29
30=item 2. Vendor allocations should be in the range 0xc000-0xfffe to reduce the
31         possibility of clashes with community IDs assigned from the bottom up.
32
33=item 3. The vendor is responsible for allocations within the range and should
34         try to record specific device IDs in PCI ID databases such as
35         https://pci-ids.ucw.cz and https://devicehunt.com
36
37=back
38
39=head1 Reservations
40
41        range     | vendor/product
42    --------------+--------------------------------------------------------------
43    0x0001        | (Xen Platform PCI device)
44    0x0002        | Citrix XenServer (grandfathered allocation for XenServer 6.1)
45    0xc000-0xc0ff | Citrix XenServer
46    0xc100-0xc1ff | Citrix XenClient
47    0xc200-0xc2ff | XCP-ng Project (https://xcp-ng.org)
48
49=head1 Notes
50
51=over 4
52
53=item 1.
54
55Upstream QEMU provides a parameterized device called xen-pvdevice that
56can be used to host guest drivers. Execute:
57
58    qemu-system-i386 -device xen-pvdevice,help
59
60for a list of all parameters. The following parameters are relevant to
61driver binding:
62
63=over 4
64
65=item  vendor-id (default 0x5853)
66
67The PCI vendor ID and subsystem vendor ID of the device.
68
69=item  device-id (must be specified)
70
71The PCI device ID and subsystem device ID of the device.
72
73=item  revision (default 0x01)
74
75The PCI revision of the device
76
77=back
78
79Also the size parameter (default 0x400000) can be used to specify the
80size of the single MMIO BAR that the device exposes. This area may be
81used by drivers for mapping grant tables, etc.
82
83Note that the presence of the Xen Platform PCI device is generally a
84pre-requisite for an additional xen-pvdevice as it is the platform
85device that provides that IO ports necessary for unplugging emulated
86devices. See hvm-emulated-unplug.markdown for details of the IO ports
87and unplug protocol.
88
89libxl provides support for creation of a single additional xen-pvdevice.
90See the vendor_device parameter in xl.cfg(5).
91
92XenServer might present a xen-pvdevice device with ID 0xC000.
93Such device is a placeholder for Windows update usage and is always exposed
94in conjunction with a Xen Platform PCI device, usually with ID 0x0002
95
96=back
97