From patchwork Thu Mar 24 17:22:39 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: George Dunlap X-Patchwork-Id: 8663191 Return-Path: X-Original-To: patchwork-xen-devel@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork2.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork2.web.kernel.org (Postfix) with ESMTP id 5A9FBC0553 for ; Thu, 24 Mar 2016 17:25:15 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id A0831201FE for ; Thu, 24 Mar 2016 17:25:13 +0000 (UTC) Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) (using TLSv1.2 with cipher AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 64D3C203E9 for ; Thu, 24 Mar 2016 17:25:12 +0000 (UTC) Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.84_2) (envelope-from ) id 1aj8y8-0000K1-NY; Thu, 24 Mar 2016 17:22:48 +0000 Received: from mail6.bemta5.messagelabs.com ([195.245.231.135]) by lists.xenproject.org with esmtp (Exim 4.84_2) (envelope-from ) id 1aj8y7-0000Jk-1X for xen-devel@lists.xen.org; Thu, 24 Mar 2016 17:22:47 +0000 Received: from [85.158.139.211] by server-2.bemta-5.messagelabs.com id 10/75-12342-66224F65; Thu, 24 Mar 2016 17:22:46 +0000 X-Env-Sender: prvs=884475cec=George.Dunlap@citrix.com X-Msg-Ref: server-10.tower-206.messagelabs.com!1458840164!14025837!1 X-Originating-IP: [66.165.176.63] X-SpamReason: No, hits=0.0 required=7.0 tests=sa_preprocessor: VHJ1c3RlZCBJUDogNjYuMTY1LjE3Ni42MyA9PiAzMDYwNDg=\n, received_headers: No Received headers X-StarScan-Received: X-StarScan-Version: 8.11; banners=-,-,- X-VirusChecked: Checked Received: (qmail 642 invoked from network); 24 Mar 2016 17:22:45 -0000 Received: from smtp02.citrix.com (HELO SMTP02.CITRIX.COM) (66.165.176.63) by server-10.tower-206.messagelabs.com with RC4-SHA encrypted SMTP; 24 Mar 2016 17:22:45 -0000 X-IronPort-AV: E=Sophos;i="5.24,386,1454976000"; d="scan'208";a="348473936" From: George Dunlap To: Date: Thu, 24 Mar 2016 17:22:39 +0000 Message-ID: <1458840160-26733-9-git-send-email-george.dunlap@citrix.com> X-Mailer: git-send-email 2.1.4 In-Reply-To: <1458840160-26733-1-git-send-email-george.dunlap@citrix.com> References: <1458840160-26733-1-git-send-email-george.dunlap@citrix.com> MIME-Version: 1.0 X-DLP: MIA2 Cc: Ian Jackson , Wei Liu , George Dunlap , Roger Pau Monne Subject: [Xen-devel] [PATCH v3 8/9] docs: Document block-script protocol X-BeenThere: xen-devel@lists.xen.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Errors-To: xen-devel-bounces@lists.xen.org Sender: "Xen-devel" X-Spam-Status: No, score=-4.2 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_MED, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Signed-off-by: George Dunlap Acked-by: Ian Jackson --- Changes since v2: - Note that the "Inputs" describe Linux only Changes since v1: - Attempt to make a clear distinction between custom hotplug scripts and the script called for raw physical devices and files CC: Ian Jackson CC: Wei Liu CC: Roger Pau Monne --- docs/misc/block-scripts.txt | 112 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) diff --git a/docs/misc/block-scripts.txt b/docs/misc/block-scripts.txt new file mode 100644 index 0000000..f9a001e --- /dev/null +++ b/docs/misc/block-scripts.txt @@ -0,0 +1,112 @@ +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 (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.