1Block scripts
2=============
3
4Block scripts are called at the moment anytime blkback is directly
5involved in providing access to a backend.  There are three general
6cases this happens:
7
81. When a user passes a block device in the 'target' field of the disk
9specification
10
112. When a user passes a file in the 'target' field of the disk
12specification
13
143. When a user specifies a custom hotplug script.
15
16Setup
17-----
18
19It is highly recommended that custom hotplug scripts as much as
20possible include and use the common Xen functionality.  If the script
21is run from the normal block script location (/etc/xen/scripts by
22default), then this can be done by adding the following to the top of
23the script:
24
25dir=$(dirname "$0")
26. "$dir/block-common.sh"
27
28
29Inputs
30------
31
32Unfortunately the inputs to the block scripts look completely
33different for each operating system.
34
35Inputs (Linux)
36--------------
37
38In all cases, the scripts are called with either "add" or "remove" as
39the command.  For custom scripts, the command will be the first
40argument of the script (i.e. $1).
41
42The environment variable XENBUS_PATH will be set to the
43path for the block device to be created.
44
45When the script is run, the following nodes shall already have been
46written into xenstore:
47
48 $XENBUS/params    The contents of the 'target' section of the disk specification verbatim.
49 $XENBUS/mode      'r' (for readonly) or 'w' (for read-write)
50
51Inputs (FreeBSD)
52--------------
53
54The scripts are always called with the same set of arguments. The first
55parameter is the xenstore backend path of the device, while the second
56argument is the action, which is always either "add" or "remove".
57
58When the script is run, the following nodes shall already have been
59written into xenstore:
60
61 $XENBUS/params    The contents of the 'target' section of the disk specification verbatim.
62 $XENBUS/mode      'r' (for readonly) or 'w' (for read-write)
63
64Inputs (NetBSD)
65---------------
66
67TODO
68
69Output
70-------
71
72Block scripts are responsible for making sure that if a file is
73provided to a VM read/write, that it is not provided to any other VM.
74
75FreeBSD block hotplug scripts must write
76"$XENBUS_PATH/physical-device-path" with the path to the physical
77device or file.  Linux and NetBSD block hotplug scripts *should* also
78write this node.
79
80For the time being, Linux and NetBSD block hotplug scripts must write
81"$XENBUS_PATH/physical-device" with the device's major and minor
82numbers, written in hex, and separated by a colon.
83
84Scripts which include block-common.sh can simply call write_dev "$dev"
85with a path to the device, and write_dev will do the right thing, now
86and going forward.  (See the discussion below.)
87
88Rationale and future work
89-------------------------
90
91Historically, the block scripts wrote a node called "physical-device",
92which contains the major and minor numbers, written in hex, and
93separated by a colon (e.g., "1a:2").  This is required by the Linux
94blkback driver.
95
96FreeBSD blkback, on the other hand, does not have the concept of
97major/minor numbers, and can give direct access to a file without
98going through loopback; so its driver will consume
99physical-device-path.
100
101On Linux, the device model (qemu) needs access to a file it can
102interpret to provide emulated disks before paravirtualized drivers are
103marked as up.  The easiest way to accomplish this is to allow qemu to
104consume physical-device-path (rather than, say, having dom0 act as
105both a frontend and a backend).
106
107Going forward, the plan is at some point to have all block scripts
108simply write "physical-device-path", and then have libxl write the
109other nodes.  The reason we haven't done this yet is that the main
110block script wants to check to make sure the *major/minor* number
111hasn't been re-used, rather than just checking that the *specific
112device node* isn't re-used.  To do this it currently uses
113physical-device; and to do this *safely* it needs physical-device to
114be written with the lock held.
115
116The simplest solution for sorting this out would be to have the block
117script use physical-device if it's present, but if not, to directly
118stat physical-device-path.  But there's not time before the 4.7
119release to make sure all that works.
120
121Another possibility would be to only call out to scripts when using
122custom hotplug scripts; and when doing files or physical devices, to
123do the duplicate checking inside of libxl instead.  The rationale for
124doing this in block scripts rather than in libxl isn't clear at thes
125point.
126