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