Re: [Xen-devel] [PATCH 7/8] docs: Document block-script protocol

[George Dunlap <dunlapg@xxxxxxxxx>]

On Wed, Mar 16, 2016 at 10:57 PM, Jim Fehlig <jfehlig@xxxxxxxx> wrote:
> On 03/16/2016 10:09 AM, George Dunlap wrote:
>> Signed-off-by: George Dunlap <george.dunlap@xxxxxxxxxx>
>> ---
>> CC: Ian Jackson <ian.jackson@xxxxxxxxxx>
>> CC: Wei Liu <wei.liu2@xxxxxxxxxx>
>> CC: Roger Pau Monne <roger.pau@xxxxxxxxxx>
>> ---
>>  docs/misc/block-scripts.txt | 100 
>> ++++++++++++++++++++++++++++++++++++++++++++
>>  1 file changed, 100 insertions(+)
>>
>> diff --git a/docs/misc/block-scripts.txt b/docs/misc/block-scripts.txt
>> new file mode 100644
>> index 0000000..ef19207
>> --- /dev/null
>> +++ b/docs/misc/block-scripts.txt
>> @@ -0,0 +1,100 @@
>> +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 script.
>> +
>> +Setup
>> +-----
>> +
>> +It is highly recommended that custom 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
>> +------
>> +
>> +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)
>> +
>> +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 do away with the block scripts
>> +altogether when not actually running any scripts,
>
> Just to clarify, do you mean drop support for all block scripts?

No -- although I can see why "do away with block scripts when not
running any scripts" is a bit confusing. :-)

What I meant was this: at the moment, when we *aren't* using custom
hotplug scripts, but we are using physical devices or files, we call a
script called "block".  What I meant was, to only run a script when a
custom hotplug script is actually requested; and in the case of
physical devices or files, get rid of the current block script and do
all the necessary work in libxl instead.

Having custom block scripts (like block-iscsi and block-drbd) is a
feature I definitely think we should keep.

I'll clarify the wording here.

>>  and do the duplicate
>> +checking inside of libxl.  The rationale for doing this in block
>> +scripts rather than in libxl isn't clear at thes point.
>
> Block scripts like block-iscsi and block-drbd also "cook" $XENBUS/params into
> $XENBUS_PATH/physical-device{,-path} right?

block-iscsi calls write_dev (as recommended in this document), so it
will always DTRT.  block-drbd must currently at least write
physical-device, or it wouldn't work.  (The "Linux block scripts must
write physical-device" is describing the implicit current protocol.)
And at least in this version of the script, block-drbd also calls
write_dev, so it will automatically be updated to the new behavior as
well:

https://www.meb.uni-bonn.de/imbie/dokus/dateien/xen-scripte/scripts/block-drbd

Nonetheless, we always need to support scripts that only write
physical-device -- at least as well as they have ever worked (which
for the time being is pv-only).  I'll try to make this clear in the
document.

 -George

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel