From patchwork Wed Mar 23 14:16:02 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Denis V. Lunev" X-Patchwork-Id: 601244 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 3qVWpr5n8lz9sDb for ; Thu, 24 Mar 2016 01:17:08 +1100 (AEDT) Received: from localhost ([::1]:44237 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aijat-0004A3-03 for incoming@patchwork.ozlabs.org; Wed, 23 Mar 2016 10:17:07 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:52393) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aijaJ-0003Ba-E6 for qemu-devel@nongnu.org; Wed, 23 Mar 2016 10:16:36 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aijaH-00066S-Ru for qemu-devel@nongnu.org; Wed, 23 Mar 2016 10:16:31 -0400 Received: from mailhub.sw.ru ([195.214.232.25]:17086 helo=relay.sw.ru) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aijaH-00062a-E9 for qemu-devel@nongnu.org; Wed, 23 Mar 2016 10:16:29 -0400 Received: from irbis.sw.ru ([10.30.2.139]) by relay.sw.ru (8.13.4/8.13.4) with ESMTP id u2NEG2Bc015153; Wed, 23 Mar 2016 17:16:08 +0300 (MSK) From: "Denis V. Lunev" To: nbd-general@lists.sourceforge.net, qemu-devel@nongnu.org Date: Wed, 23 Mar 2016 17:16:02 +0300 Message-Id: <1458742562-30624-3-git-send-email-den@openvz.org> X-Mailer: git-send-email 2.1.4 In-Reply-To: <1458742562-30624-1-git-send-email-den@openvz.org> References: <1458742562-30624-1-git-send-email-den@openvz.org> X-detected-operating-system: by eggs.gnu.org: OpenBSD 3.x X-Received-From: 195.214.232.25 Cc: Kevin Wolf , Pavel Borzenkov , Stefan Hajnoczi , Paolo Bonzini , Wouter Verhelst , den@openvz.org Subject: [Qemu-devel] [PATCH 2/2] NBD proto: add GET_LBA_STATUS extension X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org From: Pavel Borzenkov With the availability of sparse storage formats, it is often needed to query status of a particular LBA range and read only those blocks of data that are actually present on the block device. To provide such information, the patch adds GET_LBA_STATUS extension with one new NBD_CMD_GET_LBA_STATUS command. There exists a concept of data dirtiness, which is required during, for example, incremental block device backup. To express this concept via NBD protocol, this patch also adds additional mode of operation to NBD_CMD_GET_LBA_STATUS command. Since NBD protocol has no notion of block size, and to mimic SCSI "GET LBA STATUS" command more closely, it has been chosen to return a list of extents in the response of NBD_CMD_GET_LBA_STATUS command, instead of a bitmap. Signed-off-by: Pavel Borzenkov Reviewed-by: Roman Kagan Signed-off-by: Denis V. Lunev CC: Wouter Verhelst CC: Paolo Bonzini CC: Kevin Wolf CC: Stefan Hajnoczi --- doc/proto.md | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) diff --git a/doc/proto.md b/doc/proto.md index cda213c..fff515d 100644 --- a/doc/proto.md +++ b/doc/proto.md @@ -243,6 +243,8 @@ immediately after the global flags field in oldstyle negotiation: `NBD_CMD_TRIM` commands - bit 6, `NBD_FLAG_SEND_WRITE_ZEROES`; should be set to 1 if the server supports `NBD_CMD_WRITE_ZEROES` commands +- bit 7, `NBD_FLAG_SEND_GET_LBA_STATUS`; should be set to 1 if the server + supports `NBD_CMD_GET_LBA_STATUS` commands ##### Client flags @@ -477,6 +479,10 @@ The following request types exist: Defined by the experimental `WRITE_ZEROES` extension; see below. +* `NBD_CMD_GET_LBA_STATUS` (7) + + Defined by the experimental `GET_LBA_STATUS` extension; see below. + * Other requests Some third-party implementations may require additional protocol @@ -638,6 +644,82 @@ The server SHOULD return `ENOSPC` if it receives a write zeroes request including one or more sectors beyond the size of the device. It SHOULD return `EPERM` if it receives a write zeroes request on a read-only export. +### `GET_LBA_STATUS` extension + +With the availability of sparse storage formats, it is often needed to query +status of a particular LBA range and read only those blocks of data that are +actually present on the block device. + +Some storage formats and operations over such formats express a concept of +data dirtiness. Whether the operation is block device mirroring, +incremental block device backup or any other operation with a concept of +data dirtiness, they all share a need to provide a list of LBA ranges +that this particular operation treats as dirty. + +To provide such class of information, `GET_LBA_STATUS` extension adds new +`NBD_CMD_GET_LBA_STATUS` command which returns a list of LBA ranges with +their respective states. + +* `NBD_CMD_GET_LBA_STATUS` (7) + + An LBA range status query request. Length and offset define the range + of interest. The server MUST reply with a reply header, followed + immediately by the following data: + + - 32 bits, length of parameter data that follow (unsigned) + - zero or more LBA status descriptors, each having the following + structure: + + * 64 bits, offset (unsigned) + * 32 bits, length (unsigned) + * 16 bits, status (unsigned) + + unless an error condition has occurred. + + If an error occurs, the server SHOULD set the appropriate error code + in the error field. The server MUST then either close the + connection, or send *length of parameter data* bytes of data + (which MAY be invalid). + + The type of information required by the client is passed to server in the + command flags field. If the server does not implement requested type or + have no means to express it, it MUST NOT return an error, but instead MUST + return a single LBA status descriptor with *offset* and *length* equal to + the *offset* and *length* from request, and *status* set to `0`. + + The following request types are currently defined for the command: + + 1. Block provisioning state + + Upon receiving an `NBD_CMD_GET_LBA_STATUS` command with command flags + field set to `NBD_FLAG_GET_ALLOCATED` (0x0), the server MUST return + the provisioning state of the device. The following provisionnig states + are defined for the command: + + - `NBD_STATE_ALLOCATED` (0x0), LBA extent is present on the block device; + - `NBD_STATE_ZEROED` (0x1), LBA extent is present on the block device + and contains zeroes; + - `NBD_STATE_DEALLOCATED` (0x2), LBA extent is not present on the + block device. A client MUST NOT make any assumptions about the + contents of the extent. + + 2. Block dirtiness state + + Upon receiving an `NBD_CMD_GET_LBA_STATUS` command with command flags + field set to `NBD_FLAG_GET_DIRTY` (0x1), the server MUST return + the dirtiness status of the device. The following dirtiness states + are defined for the command: + + - `NBD_STATE_DIRTY` (0x0), LBA extent is dirty; + - `NBD_STATE_CLEAN` (0x1), LBA extent is clean. + + Generic NBD client implementation without knowledge of a particular NBD + server operation MUST NOT make any assumption on the meaning of the + NBD_STATE_DIRTY or NBD_STATE_CLEAN states. + +The server SHOULD return `EINVAL` if it receives a `GET_LBA_STATUS` request +including one or more sectors beyond the size of the device. + ## About this file This file tries to document the NBD protocol as it is currently