1xen-vbd-interface(7) Xen xen-vbd-interface(7)
2 Xen guest interface
6 A Xen guest can be provided with block devices. These are always pro‐
7 vided as Xen VBDs; for HVM guests they may also be provided as emulated
8 IDE, AHCI or SCSI disks.
9 The abstract interface involves specifying, for each block device:
11 • Nominal disk type: Xen virtual disk (aka xvd, the default); SCSI
13 (sd); IDE or AHCI (hd*).
14 For HVM guests, each whole-disk hd* and and sd* device is made avail‐
16 able both via emulated IDE resp. SCSI controller, and as a Xen VBD.
17 The HVM guest is entitled to assume that the IDE or SCSI disks avail‐
18 able via the emulated IDE controller target the same underlying de‐
19 vices as the corresponding Xen VBD (ie, multipath). In hd* case with
20 hdtype=ahci, disk will be AHCI via emulated ich9 disk controller.
21 For PV guests every device is made available to the guest only as a
23 Xen VBD. For these domains the type is advisory, for use by the
24 guest’s device naming scheme.
25 The Xen interface does not specify what name a device should have in
27 the guest (nor what major/minor device number it should have in the
28 guest, if the guest has such a concept).
29 • Disk number, which is a nonnegative integer, conventionally starting
31 at 0 for the first disk.
32 • Partition number, which is a nonnegative integer where by convention
34 partition 0 indicates the “whole disk”.
35 Normally for any disk either partition 0 should be supplied in which
37 case the guest is expected to treat it as they would a native whole
38 disk (for example by putting or expecting a partition table or disk
39 label on it);
40 Or only non-0 partitions should be supplied in which case the guest
42 should expect storage management to be done by the host and treat
43 each vbd as it would a partition or slice or LVM volume (for example
44 by putting or expecting a filesystem on it).
45 Non-whole disk devices cannot be passed through to HVM guests via the
47 emulated IDE or SCSI controllers.
48 Configuration file syntax
50 The config file syntaxes are, for example
51 d0 d0p0 xvda Xen virtual disk 0 partition 0 (whole disk)
53 d1p2 xvdb2 Xen virtual disk 1 partition 2
54 d536p37 xvdtq37 Xen virtual disk 536 partition 37
55 sdb3 SCSI disk 1 partition 3
56 hdc2 IDE disk 2 partition 2
57 The dp syntax is not supported by xm/xend.
59 To cope with guests which predate this specification we preserve the
61 existing facility to specify the xenstore numerical value directly by
62 putting a single number (hex, decimal or octal) in the domain config
63 file instead of the disk identifier; this number is written directly to
64 xenstore (after conversion to the canonical decimal format).
65 Concrete encoding in the VBD interface (in xenstore)
67 The information above is encoded in the concrete interface as an inte‐
68 ger (in a canonical decimal format in xenstore), whose value encodes
69 the information above as follows:
70 1 << 28 | disk << 8 | partition xvd, disks or partitions 16 onwards
72 202 << 8 | disk << 4 | partition xvd, disks and partitions up to 15
73 8 << 8 | disk << 4 | partition sd, disks and partitions up to 15
74 3 << 8 | disk << 6 | partition hd, disks 0..1, partitions 0..63
75 22 << 8 | (disk-2) << 6 | partition hd, disks 2..3, partitions 0..63
76 2 << 28 onwards reserved for future use
77 other values less than 1 << 28 deprecated / reserved
78 The 1<<28 format handles disks up to (1<<20)-1 and partitions up to
80 255. It will be used only where the 202<<8 format does not have enough
81 bits.
82 Guests MAY support any subset of the formats above except that if they
84 support 1<<28 they MUST also support 202<<8. PV-on-HVM drivers MUST
85 support at least one of 3<<8 or 8<<8; 3<<8 is recommended.
86 Some software has used or understood Linux-specific encodings for SCSI
88 disks beyond disk 15 partition 15, and IDE disks beyond disk 3 parti‐
89 tion 63. These vbds, and the corresponding encoded integers, are dep‐
90 recated.
91 Guests SHOULD ignore numbers that they do not understand or recognise.
93 They SHOULD check supplied numbers for validity.
94 Notes on Linux as a guest
96 Very old Linux guests (PV and PV-on-HVM) are able to “steal” the device
97 numbers and names normally used by the IDE and SCSI controllers, so
98 that writing “hda1” in the config file results in /dev/hda1 in the
99 guest. These systems interpret the xenstore integer as major << 8 |
100 minor where major and minor are the Linux-specific device numbers.
101 Some old configurations may depend on deprecated high-numbered SCSI and
102 IDE disks. This does not work in recent versions of Linux.
103 So for Linux PV guests, users are recommended to supply xvd* devices
105 only. Modern PV drivers will map these to identically-named devices in
106 the guest.
107 For Linux HVM guests using PV-on-HVM drivers, users are recommended to
109 supply as few hd* devices as possible, and for the rest of the disks,
110 to use pure xvd* devices starting at xvde. Modern PV-on-HVM drivers
111 will map provided hd* devices to the corresponding /dev/xvd* (for exam‐
112 ple, hda is presented also as /dev/xvda).
113 Some Linux HVM guests with broken PV-on-HVM drivers do not cope proper‐
115 ly if both hda and hdc are supplied, nor with both hda and xvda, be‐
116 cause they directly map the bottom 8 bits of the xenstore integer di‐
117 rectly to the Linux guest’s device number and throw away the rest; they
118 can crash due to minor number clashes. With these guests, the work‐
119 around is not to supply problematic combinations of devices.
120 Other frontend and backend options
122 See xen/include/public/io/blkif.h for the full list of options.
1234.16.3 2022-12-19 xen-vbd-interface(7)