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