From patchwork Thu Aug 1 17:01:28 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 816054 Delivered-To: patch@linaro.org Received: by 2002:a5d:4acf:0:b0:367:895a:4699 with SMTP id y15csp1283844wrs; Thu, 1 Aug 2024 10:02:35 -0700 (PDT) X-Forwarded-Encrypted: i=2; AJvYcCXfd+L2lpwrEYHEUsGyHvgstqoRhqJS5HPXlzr1vBkkbGKAarp/exOSUU6kysFNxemwE9865uF6jzwhpZaZztmz X-Google-Smtp-Source: AGHT+IGkrHlQPT1skvPY4gtbyqEMPCe2aoA53xD9imMdv4CiAiTh9YnMv6YgOnz8HqhDyOdU1Sbj X-Received: by 2002:a05:620a:4142:b0:7a1:d306:4ba7 with SMTP id af79cd13be357-7a34ef42ee3mr87129685a.31.1722531755266; Thu, 01 Aug 2024 10:02:35 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1722531755; cv=none; d=google.com; s=arc-20160816; b=xurPz3pBbQvtr5jKUQTP2VqbNNU9DmlZenIpX80v4+Y+hv6DZ6oaYHy1c3coz0sxji gfBC5c3R14uUL27ZtvkXfPOozKPnZ1zSs9qwyl0C5Q9I9t5+6hue6jrgcov4M/ijLi89 ISTL8V2tY8s6G3GHxFN0/y1gxnBuVRM6QzGd1T+XqvO/A87HCr1MwEFSsFxlOKpq4Bi/ 4a8m1rAcS6bCUgVKQH8o+0zBFunjaRJZLHLN3AX9ju4e2Z8zztAXKz1CW/6wPyT8sfFe /a/HyzG9flFrRaZ2IKfHOvBPXn1LZ8JSydbH0C0CTZm2O/EyOXJ5MSKhL5zWbdByVcCb WFeQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:cc:to :from:dkim-signature; bh=dw4w8DX6EHAaNzhMmT3/w3NtJlxoy987bWug5+S1bQA=; fh=riSz47MrPq+xVPO4v3MVeWxqPYtw0AT5Us8ozgPn4y0=; b=diVwQTm2QEF/igQ9INIZnJKtfRzIbrfoXzPMZCj7ll1Bo507F7GiYZgFr1ezrvMSm4 aOn+eOjNK7ufk1jsYJGy91VXH6mjo4CxPYJCsg3Ic181DupIHTdJ/ODFjVygVuC7f5Q3 m7i3XLcdpI9fPn6rUkU+bU0Y1CjLNHhA6N8bwgaT4H5UMwdKEBmvPWtuHBmf7gA6P22d upnbrHUPVq2ixqfO5zIj5N1j1HT6lgSCn56v9t9PA2HyVHAQ2s05gJpoIp/2QkcqnWWS 8UiwI1YpmxJmccxrWM5l7rH6GwX79QD4+woSWiy5AsDPSyeAsq+vwwFQkc1Cko8ObFVx w2wA==; dara=google.com ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=NCoq2Ppy; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org; dara=neutral header.i=@linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id 6a1803df08f44-6bb99b46cccsi1004566d6.265.2024.08.01.10.02.35 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Thu, 01 Aug 2024 10:02:35 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=NCoq2Ppy; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org; dara=neutral header.i=@linaro.org Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sZZBQ-0003Ff-Qj; Thu, 01 Aug 2024 13:01:44 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1sZZBN-0003BE-AX for qemu-devel@nongnu.org; Thu, 01 Aug 2024 13:01:41 -0400 Received: from mail-wm1-x336.google.com ([2a00:1450:4864:20::336]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1sZZBI-0003PR-8B for qemu-devel@nongnu.org; Thu, 01 Aug 2024 13:01:40 -0400 Received: by mail-wm1-x336.google.com with SMTP id 5b1f17b1804b1-428e1915e18so6434195e9.1 for ; Thu, 01 Aug 2024 10:01:35 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1722531694; x=1723136494; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=dw4w8DX6EHAaNzhMmT3/w3NtJlxoy987bWug5+S1bQA=; b=NCoq2Ppy4+kARIyBSI6Y2NMD6l47g8MSWSTTotjT09zVDPu+Gv6nGedqxebSblju+s dzABJ44sEO85Otgo59iOO9sCPIK9fYFoVdV3Yhb+RpEDYCKkn6v6PPzTLP/vWyuwVMyo g9XrjFnxkvPfIAM8Q2cB3uu55dWAm8XI6XEl+ECQQqkVXQDdzezQT9o/1AyRZTiejGEK bPCOpPR+vZ2MDLEZM/aTrxas4FhoTJAMny5taqnSrX/ym/+QhjV/Rd8W+n40ZdpRoInj 4t6L1/KFo3WjmIPLBn2ym+mgxiMwHTFAzBGor30F7YFYuGE4wppb3ZAcTSWD3kZJy+G9 0kqw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1722531694; x=1723136494; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=dw4w8DX6EHAaNzhMmT3/w3NtJlxoy987bWug5+S1bQA=; b=HniiADE4LvbzRXusDBcxUodwtUU9K/4EUTmnkd8GEZDPKu6aV7GZaAUxWwlqagFuyv AQTpN/AJDpjxlnrRRuxYNeQbor/nxcK30iPPFL0U2VNiMZwK/NSD/H+0H1ho4GKpSeQA DpK3Nw2P9xWEukN6OLhvSbMLPXpZdYRGaYLzZeYSzLAGE9akn4bPQOuuQSLNJ44iLRrH AiOtkZ1ft5HHhsjEkDSIIMNuoi9ishN29p+6QWR04BL5i4/xMI+yCc1CCNd82Li7HuHi JhzsasGPHBDgz891cE0arhGskilXtj//LQZwC4eHRwcSviCMx2li1d6gNhwKkIWNiq81 MVxg== X-Gm-Message-State: AOJu0Yworgl3A585CYWOL43HsYASaeW7D5GUt1Dd808+Ga6n0d7dDwpC HNSq51D27SzQp1K7yNu0DyrRWHzMDeZe9WZ6Ylltfd9lHokCR30mgQq19v35M/1HZhsveq3/cA7 i X-Received: by 2002:a05:600c:314a:b0:426:6688:2421 with SMTP id 5b1f17b1804b1-428e6b059a6mr3862475e9.11.1722531693854; Thu, 01 Aug 2024 10:01:33 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [2001:8b0:1d0::2]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-428e24c2b4csm30385255e9.31.2024.08.01.10.01.33 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 01 Aug 2024 10:01:33 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Cc: Eric Blake , Vladimir Sementsov-Ogievskiy , Stefan Hajnoczi , "Denis V. Lunev" , Jiri Pirko Subject: [PATCH 2/5] docs/interop/nbd.txt: Convert to rST Date: Thu, 1 Aug 2024 18:01:28 +0100 Message-Id: <20240801170131.3977807-3-peter.maydell@linaro.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240801170131.3977807-1-peter.maydell@linaro.org> References: <20240801170131.3977807-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::336; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x336.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: qemu-devel-bounces+patch=linaro.org@nongnu.org Convert nbd.txt to rST format. Signed-off-by: Peter Maydell Reviewed-by: Eric Blake --- MAINTAINERS | 2 +- docs/interop/index.rst | 1 + docs/interop/nbd.rst | 89 ++++++++++++++++++++++++++++++++++++++++++ docs/interop/nbd.txt | 72 ---------------------------------- 4 files changed, 91 insertions(+), 73 deletions(-) create mode 100644 docs/interop/nbd.rst delete mode 100644 docs/interop/nbd.txt diff --git a/MAINTAINERS b/MAINTAINERS index 2a183fe960b..dd159053dbd 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -3869,7 +3869,7 @@ F: nbd/ F: include/block/nbd* F: qemu-nbd.* F: blockdev-nbd.c -F: docs/interop/nbd.txt +F: docs/interop/nbd.rst F: docs/tools/qemu-nbd.rst F: tests/qemu-iotests/tests/*nbd* T: git https://repo.or.cz/qemu/ericb.git nbd diff --git a/docs/interop/index.rst b/docs/interop/index.rst index ed65395bfb2..b9ceaabc648 100644 --- a/docs/interop/index.rst +++ b/docs/interop/index.rst @@ -14,6 +14,7 @@ are useful for making QEMU interoperate with other software. dbus-vmstate dbus-display live-block-operations + nbd pr-helper qmp-spec qemu-ga diff --git a/docs/interop/nbd.rst b/docs/interop/nbd.rst new file mode 100644 index 00000000000..de079d31fd8 --- /dev/null +++ b/docs/interop/nbd.rst @@ -0,0 +1,89 @@ +QEMU NBD protocol support +========================= + +QEMU supports the NBD protocol, and has an internal NBD client (see +``block/nbd.c``), an internal NBD server (see ``blockdev-nbd.c``), and an +external NBD server tool (see ``qemu-nbd.c``). The common code is placed +in ``nbd/*``. + +The NBD protocol is specified here: +https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md + +The following paragraphs describe some specific properties of NBD +protocol realization in QEMU. + +Metadata namespaces +------------------- + +QEMU supports the ``base:allocation`` metadata context as defined in the +NBD protocol specification, and also defines an additional metadata +namespace ``qemu``. + +``qemu`` namespace +------------------ + +The ``qemu`` namespace currently contains two available metadata context +types. The first is related to exposing the contents of a dirty +bitmap alongside the associated disk contents. That metadata context +is named with the following form:: + + qemu:dirty-bitmap: + +Each dirty-bitmap metadata context defines only one flag for extents +in reply for ``NBD_CMD_BLOCK_STATUS``: + +bit 0: + ``NBD_STATE_DIRTY``, set when the extent is "dirty" + +The second is related to exposing the source of various extents within +the image, with a single metadata context named:: + + qemu:allocation-depth + +In the allocation depth context, the entire 32-bit value represents a +depth of which layer in a thin-provisioned backing chain provided the +data (0 for unallocated, 1 for the active layer, 2 for the first +backing layer, and so forth). + +For ``NBD_OPT_LIST_META_CONTEXT`` the following queries are supported +in addition to the specific ``qemu:allocation-depth`` and +``qemu:dirty-bitmap:``: + +``qemu:`` + returns list of all available metadata contexts in the namespace +``qemu:dirty-bitmap:`` + returns list of all available dirty-bitmap metadata contexts + +Features by version +------------------- + +The following list documents which qemu version first implemented +various features (both as a server exposing the feature, and as a +client taking advantage of the feature when present), to make it +easier to plan for cross-version interoperability. Note that in +several cases, the initial release containing a feature may require +additional patches from the corresponding stable branch to fix bugs in +the operation of that feature. + +2.6 + ``NBD_OPT_STARTTLS`` with TLS X.509 Certificates +2.8 + ``NBD_CMD_WRITE_ZEROES`` +2.10 + ``NBD_OPT_GO``, ``NBD_INFO_BLOCK`` +2.11 + ``NBD_OPT_STRUCTURED_REPLY`` +2.12 + ``NBD_CMD_BLOCK_STATUS`` for ``base:allocation`` +3.0 + ``NBD_OPT_STARTTLS`` with TLS Pre-Shared Keys (PSK), + ``NBD_CMD_BLOCK_STATUS`` for ``qemu:dirty-bitmap:``, ``NBD_CMD_CACHE`` +4.2 + ``NBD_FLAG_CAN_MULTI_CONN`` for shareable read-only exports, + ``NBD_CMD_FLAG_FAST_ZERO`` +5.2 + ``NBD_CMD_BLOCK_STATUS`` for ``qemu:allocation-depth`` +7.1 + ``NBD_FLAG_CAN_MULTI_CONN`` for shareable writable exports +8.2 + ``NBD_OPT_EXTENDED_HEADERS``, ``NBD_FLAG_BLOCK_STATUS_PAYLOAD`` diff --git a/docs/interop/nbd.txt b/docs/interop/nbd.txt deleted file mode 100644 index 18efb251de9..00000000000 --- a/docs/interop/nbd.txt +++ /dev/null @@ -1,72 +0,0 @@ -QEMU supports the NBD protocol, and has an internal NBD client (see -block/nbd.c), an internal NBD server (see blockdev-nbd.c), and an -external NBD server tool (see qemu-nbd.c). The common code is placed -in nbd/*. - -The NBD protocol is specified here: -https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md - -The following paragraphs describe some specific properties of NBD -protocol realization in QEMU. - -= Metadata namespaces = - -QEMU supports the "base:allocation" metadata context as defined in the -NBD protocol specification, and also defines an additional metadata -namespace "qemu". - -== "qemu" namespace == - -The "qemu" namespace currently contains two available metadata context -types. The first is related to exposing the contents of a dirty -bitmap alongside the associated disk contents. That metadata context -is named with the following form: - - qemu:dirty-bitmap: - -Each dirty-bitmap metadata context defines only one flag for extents -in reply for NBD_CMD_BLOCK_STATUS: - - bit 0: NBD_STATE_DIRTY, set when the extent is "dirty" - -The second is related to exposing the source of various extents within -the image, with a single metadata context named: - - qemu:allocation-depth - -In the allocation depth context, the entire 32-bit value represents a -depth of which layer in a thin-provisioned backing chain provided the -data (0 for unallocated, 1 for the active layer, 2 for the first -backing layer, and so forth). - -For NBD_OPT_LIST_META_CONTEXT the following queries are supported -in addition to the specific "qemu:allocation-depth" and -"qemu:dirty-bitmap:": - -* "qemu:" - returns list of all available metadata contexts in the - namespace. -* "qemu:dirty-bitmap:" - returns list of all available dirty-bitmap - metadata contexts. - -= Features by version = - -The following list documents which qemu version first implemented -various features (both as a server exposing the feature, and as a -client taking advantage of the feature when present), to make it -easier to plan for cross-version interoperability. Note that in -several cases, the initial release containing a feature may require -additional patches from the corresponding stable branch to fix bugs in -the operation of that feature. - -* 2.6: NBD_OPT_STARTTLS with TLS X.509 Certificates -* 2.8: NBD_CMD_WRITE_ZEROES -* 2.10: NBD_OPT_GO, NBD_INFO_BLOCK -* 2.11: NBD_OPT_STRUCTURED_REPLY -* 2.12: NBD_CMD_BLOCK_STATUS for "base:allocation" -* 3.0: NBD_OPT_STARTTLS with TLS Pre-Shared Keys (PSK), -NBD_CMD_BLOCK_STATUS for "qemu:dirty-bitmap:", NBD_CMD_CACHE -* 4.2: NBD_FLAG_CAN_MULTI_CONN for shareable read-only exports, -NBD_CMD_FLAG_FAST_ZERO -* 5.2: NBD_CMD_BLOCK_STATUS for "qemu:allocation-depth" -* 7.1: NBD_FLAG_CAN_MULTI_CONN for shareable writable exports -* 8.2: NBD_OPT_EXTENDED_HEADERS, NBD_FLAG_BLOCK_STATUS_PAYLOAD