Block scripts
=============

Block scripts are called at the moment anytime blkback is directly
involved in providing access to a backend.  There are three general
cases this happens:

1. When a user passes a block device in the 'target' field of the disk
specification

2. When a user passes a file in the 'target' field of the disk
specification

3. When a user specifies a custom hotplug script.

Setup
-----

It is highly recommended that custom hotplug scripts as much as
possible include and use the common Xen functionality.  If the script
is run from the normal block script location (/etc/xen/scripts by
default), then this can be done by adding the following to the top of
the script:

dir=$(dirname "$0")
. "$dir/block-common.sh"


Inputs
------

Unfortunately the inputs to the block scripts look completely
different for each operating system.

Inputs (Linux)
--------------

In all cases, the scripts are called with either "add" or "remove" as
the command.  For custom scripts, the command will be the first
argument of the script (i.e. $1).

The environment variable XENBUS_PATH will be set to the
path for the block device to be created.

When the script is run, the following nodes shall already have been
written into xenstore:

 $XENBUS/params    The contents of the 'target' section of the disk specification verbatim.
 $XENBUS/mode      'r' (for readonly) or 'w' (for read-write)

Inputs (FreeBSD)
--------------

The scripts are always called with the same set of arguments. The first
parameter is the xenstore backend path of the device, while the second
argument is the action, which is always either "add" or "remove".

When the script is run, the following nodes shall already have been
written into xenstore:

 $XENBUS/params    The contents of the 'target' section of the disk specification verbatim.
 $XENBUS/mode      'r' (for readonly) or 'w' (for read-write)

Inputs (NetBSD)
---------------

TODO

Output
-------

Block scripts are responsible for making sure that if a file is
provided to a VM read/write, that it is not provided to any other VM.

FreeBSD block hotplug scripts must write
"$XENBUS_PATH/physical-device-path" with the path to the physical
device or file.  Linux and NetBSD block hotplug scripts *should* also
write this node.

For the time being, Linux and NetBSD block hotplug scripts must write
"$XENBUS_PATH/physical-device" with the device's major and minor
numbers, written in hex, and separated by a colon.

Scripts which include block-common.sh can simply call write_dev "$dev"
with a path to the device, and write_dev will do the right thing, now
and going forward.  (See the discussion below.)

Rationale and future work
-------------------------

Historically, the block scripts wrote a node called "physical-device",
which contains the major and minor numbers, written in hex, and
separated by a colon (e.g., "1a:2").  This is required by the Linux
blkback driver.

FreeBSD blkback, on the other hand, does not have the concept of
major/minor numbers, and can give direct access to a file without
going through loopback; so its driver will consume
physical-device-path.

On Linux, the device model (qemu) needs access to a file it can
interpret to provide emulated disks before paravirtualized drivers are
marked as up.  The easiest way to accomplish this is to allow qemu to
consume physical-device-path (rather than, say, having dom0 act as
both a frontend and a backend).

Going forward, the plan is at some point to have all block scripts
simply write "physical-device-path", and then have libxl write the
other nodes.  The reason we haven't done this yet is that the main
block script wants to check to make sure the *major/minor* number
hasn't been re-used, rather than just checking that the *specific
device node* isn't re-used.  To do this it currently uses
physical-device; and to do this *safely* it needs physical-device to
be written with the lock held.

The simplest solution for sorting this out would be to have the block
script use physical-device if it's present, but if not, to directly
stat physical-device-path.  But there's not time before the 4.7
release to make sure all that works.

Another possibility would be to only call out to scripts when using
custom hotplug scripts; and when doing files or physical devices, to
do the duplicate checking inside of libxl instead.  The rationale for
doing this in block scripts rather than in libxl isn't clear at thes
point.