1xen-vbd-interface(7)                  Xen                 xen-vbd-interface(7)
2
3
4
5   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
10       The abstract interface involves specifying, for each block device:
11
12       • Nominal  disk  type:  Xen  virtual  disk (aka xvd, the default); SCSI
13         (sd); IDE or AHCI (hd*).
14
15         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
22         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
26         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
30       • Disk  number, which is a nonnegative integer, conventionally starting
31         at 0 for the first disk.
32
33       • Partition number, which is a nonnegative integer where by  convention
34         partition 0 indicates the “whole disk”.
35
36         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
41         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
46         Non-whole disk devices cannot be passed through to HVM guests via the
47         emulated IDE or SCSI controllers.
48
49   Configuration file syntax
50       The config file syntaxes are, for example
51
52                 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
58       The dp syntax is not supported by xm/xend.
59
60       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
66   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
71               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
79       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
83       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
87       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
92       Guests  SHOULD ignore numbers that they do not understand or recognise.
93       They SHOULD check supplied numbers for validity.
94
95   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
104       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
108       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
114       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
121   Other frontend and backend options
122       See xen/include/public/io/blkif.h for the full list of options.
123
124
125
1264.16.3                            2022-12-19              xen-vbd-interface(7)
Impressum