xen-devel.lists.xenproject.org archive mirror
 help / color / mirror / Atom feed
From: George Dunlap <dunlapg@umich.edu>
To: Jim Fehlig <jfehlig@suse.com>
Cc: Ian Jackson <ian.jackson@citrix.com>,
	Roger Pau Monne <roger.pau@citrix.com>,
	Wei Liu <wei.liu2@citrix.com>,
	George Dunlap <george.dunlap@citrix.com>,
	"xen-devel@lists.xen.org" <xen-devel@lists.xen.org>
Subject: Re: [PATCH 7/8] docs: Document block-script protocol
Date: Thu, 17 Mar 2016 09:55:49 +0000	[thread overview]
Message-ID: <CAFLBxZZ3TeTWB6dmtv8Roj+Q61EJLoTpXsNERVuKd5Yr23MjqA@mail.gmail.com> (raw)
In-Reply-To: <56E9E4DC.2050909@suse.com>

On Wed, Mar 16, 2016 at 10:57 PM, Jim Fehlig <jfehlig@suse.com> wrote:
> On 03/16/2016 10:09 AM, George Dunlap wrote:
>> Signed-off-by: George Dunlap <george.dunlap@citrix.com>
>> ---
>> CC: Ian Jackson <ian.jackson@citrix.com>
>> CC: Wei Liu <wei.liu2@citrix.com>
>> CC: Roger Pau Monne <roger.pau@citrix.com>
>> ---
>>  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


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


Xen-devel mailing list

  reply	other threads:[~2016-03-17  9:55 UTC|newest]

Thread overview: 25+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2016-03-16 16:09 [PATCH 0/8] tools: Allow HVM domains emulated access to disks provided by hotplug scripts George Dunlap
2016-03-16 16:09 ` [PATCH 1/8] tools/hotplug: Add a "dummy" hotplug script for testing George Dunlap
2016-03-16 16:54   ` Ian Jackson
2016-03-16 16:09 ` [PATCH 2/8] libxl: Remove redundant setting of phyical-device George Dunlap
2016-03-16 16:54   ` Ian Jackson
2016-03-16 16:09 ` [PATCH 3/8] tools/hotplug: Write physical-device-path in addition to physical-device George Dunlap
2016-03-16 16:56   ` Ian Jackson
2016-03-16 16:57     ` George Dunlap
2016-03-16 16:09 ` [PATCH 4/8] libxl: Move check for local access to a funciton George Dunlap
2016-03-16 16:58   ` Ian Jackson
2016-03-16 17:02     ` George Dunlap
2016-03-17 18:11   ` Ian Jackson
2016-03-21 15:35     ` George Dunlap
2016-03-16 16:09 ` [PATCH 5/8] libxl: Share logic for finding path between qemuu and pygrub George Dunlap
2016-03-17 18:22   ` Ian Jackson
2016-03-18 17:09     ` George Dunlap
2016-04-01 14:17       ` Ian Jackson
2016-03-16 16:09 ` [PATCH 6/8] libxl: Allow local access for block devices with hotplug scripts George Dunlap
2016-03-17 18:36   ` Ian Jackson
2016-03-18 17:17     ` George Dunlap
2016-03-16 16:09 ` [PATCH 7/8] docs: Document block-script protocol George Dunlap
2016-03-16 22:57   ` Jim Fehlig
2016-03-17  9:55     ` George Dunlap [this message]
2016-03-17 18:38   ` Ian Jackson
2016-03-16 16:09 ` [PATCH 8/8] DO NOT APPLY libxl: Change hotplug script interface to use physical-device-path George Dunlap

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=CAFLBxZZ3TeTWB6dmtv8Roj+Q61EJLoTpXsNERVuKd5Yr23MjqA@mail.gmail.com \
    --to=dunlapg@umich.edu \
    --cc=george.dunlap@citrix.com \
    --cc=ian.jackson@citrix.com \
    --cc=jfehlig@suse.com \
    --cc=roger.pau@citrix.com \
    --cc=wei.liu2@citrix.com \
    --cc=xen-devel@lists.xen.org \


* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).